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PREFACE 



This manual describes how to write user extensions to the 
Multics Emacs editor. The reader should be thoroughly familiar 
with the Emacs editor, proficient in its use, and acquainted with 
its visible organization » The Emacs Text Editor User ' s Guide , 
Order No. CH27, provides this necessary information. The 
methods for writing terminal control modules (CTLs) to support 
additional terminal types are also described here. 



Programming knowledge is not necessary to write extensions 

introduction to extension writing. Section 2 provides a short 
course in Lisp, the programming language used for writing 
extensions, and the language in which the Emacs editor itself is 
written. Basically, the extension writer only needs to learn 
enough about Lisp to be able to imitate examples. 



Section 3 shows, by example, how to write extensions. It 
includes the functions and forms most likely to be needed by the 
extension writer. Section 4 describes LDEBUG mode, the Emacs 
mode for debugging the Lisp code used in extensions. Finally, 
Section 5 demonstrates how to write a CTL to support a new 
terminal type. Again, the CTL writer uses existing CTLs to learn 
to write his own. 



The information and specifications in this document are subject to change without notice. This doc- 
ument contains information about Honeywell products or services that may not be available out- 
side the United States. Consult your Honeywell Marketing Representative. 

©Honeywell Information Systems Inc., 1983 File No.: 1L33, 1U33 
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This manual contains sufficient information to effectively 
write and debug Multics Emacs extensions. However, it is not 
intended to be a reference document for either Lisp, in general> 
or Multics MacLisp. Reference documentation for MacLisp is 
available from: 

MIT Information Processing Center 
Publications Office 
60 Vassar Street 
Cambridge, MA 02139 



Significant Changes in CJ52 ~ 01A 

New Emacs functions include: 

kill-pop 
kill-ring-top 
reverse-regexp- search 
rotate- kill-ring 



New defcom. keywords include: 

Sccleanup 

^epilogue 

&inverse 

Scnumeric- function 



For purposes of clarity and ease of use, the MPM set has 
been reorganized* The six former- MPM manuals, the Tools manual, 
and the RCP Users' Guide have been consolidated into a new set of 
three manuals: 

Multics Programmer's Reference Manual (AG91) 

contains all the reference material from the former 
eight manuals. 

Multics Commands and Active Functions (AG92) 

contains all the commands and active functions from the 
former eight manuals. 

Multics Subroutines and Input/Output Modules (AG93) 

contains all the subroutines and I/O modules from the 
former eight manuals. 
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The following manuals are obsolete: 



Name Order No . 

MPM Peripheral Input/Output AX49 

MPM Subsystem Writers' Guide AK92 

Programming Tools A203 

MPM Communications I/O CC92 

Resource Control Users' Guide CT38 
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SECTION 1 



INTRODUCTION 



An editor extension is a user-provided capability, which is 
added to the editor to extend its power. It is different from a 
macro, which is simply a collection of editor requests gathered 
up and (perhaps) given a name. Extensions are programs ; they are 
written in the language of the Multics Emacs environment. An 
extension is a body of code that augments the editor's 
capability, but does not embed or require knowledge of how data 
in the editor is stored or manipulated. In this sense, all of 
the word, sentence, paragraph, and Lisp-list requests, and the 
various "modes" (e.g., PL/I mode) are extensions. 



The person who wishes to add to his Emacs environment any 
powerful or sophisticated capability must learn to write 
extensions. The keyboard macro facility , ^X) ) is not 

intended for such usage. This manual explains how to write 
extensions. 



One of the guiding design principles in the Emacs editor was 
that the creation of editor extensions, either by the editor 
implementors or end users, should be in a programming language of 
established elegance and power. Lisp was the language chosen. 
This primer gives you a starting point for writing Lisp code to 
run as editor extensions in the Emacs environment. If you have 
some knowledge of Lisp already, it will be of value. However, it 
is assumed in this manual that the reader has no familiarity with 
Lisp, but does, perhaps, with PL/I or BASIC. 



For examples of extension coding, the extension writer's 
ultimate reference material will be the Emacs source. The Emacs 
mail system (RMAIL) , FORTRAN and PL/I modes, and the code for the 
word, sentence, and paragraph requests (along with most of the 
other code in the Emacs module e_macops__. lisp) are standard 
examples of extension code. Techniques, styles, and subtleties 
difficult to convey in print may be gleaned by careful study of 
this code. 
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SECTION 2 



AN INTRODUCTION TO LISP 



Lisp programs are built of functions > which are similar to 
procedures or subroutines in other languages, although more akin 
to PL/I and ALGOL functions. You write a Lisp program by 
creating a file full of function definitions . A function 
definition specifies the name of a function, and what it does. 
Here is a sample function definition: 

(defun addandmult (a b c) ;This is a comment 

(* (- a b) 
{+ a b c))) 

This defines a function named addandmult that takes three 
arguments, called a, b, and c. The addandmult function computes 
the result of multiplying the difference of a and b by the sum of 
a. b- and c, and returns that number as a result or value. The 
semicolon on the first line above begins a comment ; comments 
throughout the examples provide some additional information about 
the code. 



Here is another function definition: 

(defun squareprint (arg) 

(print "The square of") 
(print arg) 
(print "is") 
(print (* arg arg) ) 
5) 



This function prints the message "The square of", prints the 
value of its argument, prints the word "is", and prints the value 
of the square of its argument. In addition, it returns the value 
5. The function "squareprint" has side effects: it causes 
output on the terminal. It also returns a value, the number 5. 
Note that all Lisp functions produce a value; only some produce 
side effects. The first function defined returns the product of 
those numbers as a value; the second returns 5. 
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If you look at squareprint, you see that it consists of 
several statements, the "print statements" that print things. 
These statements are called forms, and they are, in fact, calls 
to other functions, in this- case the builtin print function. In 
the form: 

(print "The square of") 

the: string "The square of" is being passed as an argument to the 
print" function. Like all functions, print returns a value, which 
is not used in this case.. The side effect of printing something 
doe Si occur.. In the formr 

(+■ a b c) 

you are invoking the ">" function, which is also builtin. The 
values of the parameter variables a, b, and c are passed to it as 
arguments. It returns a value, which is the requested sum, and 
produces no. side eff ects* 



There are five forms in the function-definition for 
squareprint ; 

(print "The square of") 
(print arg) 
(print "is") 
(print (* arg arg)) 
5 



Forms immediately inside a function definition are executed 
sequentially, like statements in other programming languages. 
The value produced by the last form is the one the function 
itself returns. What does it mean to "execute" a 5? Execute is 
not exactly the right term? what really happens is that these 
forms are evaluated . This means that a value is produced from 
them. Evaluating a 5 produces the number 5; evaluating the form: 

(+ a b c) 

calls the "+" function with the appropriate arguments, and 
produces whatever value the "+" function returns. The value 
produced by the "print" function is something that is not 
interesting, but a value is produced. 
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Numbers, like 5, and strings, like "The square of", are said 
to evaluate to themselves. Things between parentheses, like: 



(+ a b c ) 

(print "The square of") 



are calls to functions, which are evaluated by calling the 
function indicated, and producing the value it returns. 



Function calls have the syntax: 



(FUNCTIONNAME ARGFORMl ARGF0RM2 ARGF0RM3 ... ARGFORMn) 

where FUNCTIONNAME is the name of the function to call and the 
ARGFORMs are themselves forms, which are evaluated to produce the 
arguments to give to the function. Thus, to evaluate (i.e., 
"execute" and find the value returned) a form like: 

(+ (* a b) ■ 
15 
c) 

a evaluate the inner form (* a b) to produce a value 

a evaluate the 15 to produce 15 (remember, numbers and 
strings evaluate to themselves) 

a evaluate the variable c to produce its value 

a pass these three values on to the "+" function, and 
return what it returns. 



The newlines are ignored. 



Thus, forms are either numbers like 5, strings like "is", 
variables like b, or function calls like (* a b). 



Variables are much like variables in other languages. A 
variable has a value, which is called its binding . At this 
stage, assume that this value must be a string or a number. When 
a function is invoked, the parameter variables (like a, b, and c 
above) of the function acquire the arguments of the function call 
as bindings. Evaluating a variable produces its binding as a 
value. For instance, if someplace in a function you evaluate the 
form: 



(addandmult 2 (+ 3 2) 6) 
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a, b, and c will have the bindings 2, 5, and 6 while the forms in 
the definition of addandmult are being evaluated. This is not 
unlike the subroutine parameter mechanism in other languages. It 
is different insofar as it specifies what value a variable has 
during "subroutine" execution. In PL/I or FORTRAN, a parameter 
is associated with a variable in the calling program, not a 
value, during subroutine execution. 



There are parameter variables, as used above, temporary 
variables, described below, and global variables^. Regardless of 
the kind of variable, thev all have- bindings (values) , and 
evaluation of the variable produces that value ♦ 



To summarize:- 

1., Lis-g programs are built of functions. 

2* Function definitions consist of the word "defun", the 
function's name, a parameter list, and a number of 
forms, which are to be sequentially evaluated at 
function call time, with a pair of parentheses around 
the whole thing. 

3^.. The value of the last form in a function is the value 
returned by that function. 

4» Forms can be strings, nximbers, variables, or calls to 
functions. Forms are evaluated to produce values, 
which are passed betweerT functions as arguments and 
results. 

5^. Strings and numbers evaluate to themselves. 

6. Variables evaluate to the datum to which they are 
bound, which, for a parameter, is the corresponding 
argument to the containing function. 

7. Function calls contain the name of a function to call 
and forms that are evaluated to produce the arguments 
to the function. Function calls may produce side 
effects. Like any form, when a function call is 
evaluated, it produces a value. 
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PREDICATES 



Progranuning languages need conditional execution. In order 
to control conditional execution, you need things upon which to 
base a decision. Two data objects in the Lisp world correspond 
to truth and falsity, for the purposes of parts of the Lisp 
system that deal with conditions, A set of functions called 
predicates return these objects as values. For instance, a 
function called ">", invoked as: 

{> 4 6) 

returns the indicator of falsity, and when invoked as: 
(> 4 1) 

returns the indicator of truth. Predicates work just like other 
builtin and nonbuiltin functions, like print, addandmult, 
sguareprint, and +. They take arguments, and produce a result. 
In the case of predicates, however, the result is not a string or 
a number, but an indication of truth or falsity. The result of a 
predicate can be used by the if^ special form (see below) to 
control the execution of a function. 



The following are some of the most useful Lisp predicates. 
In all of these examples, Al, A2, SI, 01, etc., stand for forms , 
which means they can be 12, (+ 6 q), (myfun 33 (- a b)), etc, 
"Al is a number," below, means that Al is some form which 
evaluates to a number, such as 3, (+6 2), or x49, if x49*s value 
is indeed a number. 



Predicate for Numbers 

Al and A2 are numbers: 
Predicate Example Returns TRUTH if otherwise falsity. 



s (= Al A2) Al and A2 are the same number, 

> (> Al A2) Al is a bigger number than A2, 

< (< Al A2) Al is a smaller number than A2. 
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Predicates for Strings 



SI and S2 are strings: 

samepnamep 

( samepnamep Si S2) 

SI and S2 are strings of identical content, i.e., the 
"same string". This is the standard way to see if two 
strings are the same,^ as in (samepnamep test "-hold") 

alphalessp 

(alphalessp SI S2} 

SI collates before S2 alphabetically, e.g., 
(alphalessp "Able"' "Baker") returns truth, but 
(alphalessp "Zeke" "Joe") does not. 



Predicates for Any Objects 

01 is some object, of perhaps unknown type (objects are 
discussed later) : 

eq (eq 01 02) 01 and 02 are the same symbol 

or the same cons. 

fixp (fixp 01) 01 is a number, as opposed to 

some other kind of object. 

stringp (stringp 01) 01 is a string, as opposed to 

anything else. 

symbolp (symbolp 01) 01 is a symbol, as opposed to 

anything else. 

null (null 01) 01 is not only a symbol, but 

the important and 
critical symbol named "nil". 



LISP SPECIAL FORMS 

A number of special forms in Lisp do not go by the simple 
rules given above. You have already seen one. The 
function-defining form, which begins with the word "defun", is 
not simply a function call with forms to produce the function's 
arguments. By all rights, a form like: 

(defun square (x) 
(* X X)) 

should evaluate, in order, to produce arguments for "defun": 
1. A variable named "square". 



2-6 



CJ52-01 



2. The form, (x), calling a function named "x" with no 
arguments, 

3. The form, (* x x), multiplying the value of a variable 
named "x" by. itself, 

This form should then pass these three values on to the defun 
function. This, however, is not what actually happens. 
Evaluating the defun form causes a function named square to be 
defined, whose parameter list and "body" are as given. Defun is 
^ special form , and when Lisp sees "defun" as the function name 
in a form, it acts in a special way. In this case. Lisp defines 
a function built out of this form itself . The above is not a 
call to defun with arguments. It may seem unusual, but you must 
have at least one such special form in order to have an operative 
Lisp system. 



The if Special Form 

A special form in the Multics Emacs Lisp environment, called 
if , controls conditional evaluation. An example of its use: 

(defun which-is-greater (first second) 
(if (> first second) 

(print "The first one is the greater.") 
else 

(if (> second first) 

(print "The second one is greater") 
else 

(print "They are equal"))) 

The syntax of if is as follows? . 

(if <PREDICATE> 
<THEN-F0RM-1> 
<THEN-F0RM-2> 

<THEN-FORM-m> 
else 

<ELSE-F0RM-1> 
<ELSE-F0RM-2> 
... 

<ELSE-FORM-n> ) 



Any number, including none, of THEN-FORMs can be supplied. 
Similarly, any number, including none, of the ELSE-FORMs can be 
given. If there are no ELSE-FORMs, then the keyword "else" may 
be omitted, too. 
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Note that all the forms in the if are not sequentially 
evaluated? the word else is not even intended to be a form. If 
all of the forms inside the if were evaluated, it would be 
useless, for evaluation would not be conditional. That is why if 
is a special form; there are special rules about how forms inside 
it are to be evaluated. The rule for all nonspecial forms is the 
same: you evaluate all the subforms sequentially to produce the 
arguments to the function. Each special form has its own rules. 



The if special form' evaluates the PREDICATE: if it results 
in truth,- the THEN-FORMs: are sequentially evaluated, and the 
value of the last one is- returned, as the value of the if. 
Otherwise, the ELSE'-FORMs are evaluated sequentially, and the 
value of the last returned. If there are none, the symbol nil 
(see below) is returned.. 



There are two global variables in Lisp, called "t" and 
"nil", whose bindings are always the truth and falsity 
indicators, respectively ► Thus: 

(if t 

(Drin^' "Tr^1^b'»^ 

X g'— —• - - — — i- / 

else 

(print "Not so truth")) 
when evaluated, always prints "Truth". 



The actual object used as the indicator of falsity is the 
symbol named nil (see "Symbols" below). All predicates return 
this symbol to indicate falsity. The usual indicator of truth is 
the symbol named t; however, all special forms and functions that 
test predicates consider any object, other than nil, to be an 
indicator of truth. Thus, many functions return the symbol named 
nil to indicate failure and some "good" value (not nil) to 
indicate success. 



The setq Special Form 

Variables acquire values by being parameters, and acquiring 
values at function call time. In addition, variable values can 
be changed by the special form setq : 

(defun adder-of-one (x) 

(print "The value of x is") 
(print x) 

("And the value of x plus one is") 
(setq X (+ X 1) ) 
(print X) ) 
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A setq form has the word " setg " , the name of a variable, and an 
inside form. The inside form is evaluated, and that value 
assigned to the variable. It is like an assignment statement in 
other languages. 



The do-forever and stop-doing Special Forms 

The construct for looping in the Emacs Lisp environment is 
also a special form, called do-forever ; 

(do-forever 

(print "Yay Multics") 
(print "scitluM yaY" ) ) 

When evaluated, it prints these two sayings forever. The way you 
stop doing in a do-forever is to evaluate the stop-doing special 
form: 

(defun print-n-times (n) 
(do-forever 

(if (= n 0) (stop-doing) ) 
(print "foo") 
(setq n (- n 1)))) 

This function, given a number as an argument, prints "foo" that 
many times. The "=" builtin function/predicate compares its two 
arguments, which must be numbers, and returns truth or falsity 
depending on whether or not they are numerically equal. The 
arguments to = are not n and 0, but rather, the numbers that are 
the bindings of n and 0. The number which is the binding of n is 
different each time around the loop? that is the point of the 
program. It is setq that changes the value of n each time 
around, as do-forever executes the loop. A do-forever form 
generally returns something useless (nil), unless you exit by 
saying (return 5) or (return nil), or (return a). In the latter 
case, the value of the variable a is returned. 



The let Special Form 

You can acquire temporary variables via the let special 

form: 

(defun sumtimesdif (x y) 
(let ( (sum (+ X y) ) 
(dif (- X y))) 
(print "Sum times difference is ") 
(print (* sum dif ) ) 
(print "Sum squared is") 
(print (* sum sum)))) 
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This function has two temporary variables, sum and dif, which are 
initialized to the values of (+ x y) and (- x y). The general 
syntax of let is: 

(let ((VARl VALl) 

(VAR2 VAL2) 

• • • •'»»'• »'»•■•- 

(VARn VALn)) 
<F0RM1> 
<F0RM2> 

•r ar » *. •> 

<FORMm>) 



The temporary variables VARl. ..VARn exist only within the 
let* They get the initial values of VALl through VALn, which are 
forms that will be evaluated. All the VALs are evaluated before 
any of their values are assigned to the VARs. Then, with all 
these temporary variables set up and initialized, each FORMi is 
evaluated sequentially, and the value of the last FORMi is 
returned by let., 



The prog and go Special Forms 

Another, less useful way of acquiring temporary variables is 
via the special form prog . Forms inside a prog are evaluated 
sequentially, like forms in a function definition. However, the 
first form in a prog is not really a form at all, but a list of 
temporary variables used in the prog, such as "(a b c)". That is 
why prog is a special form. The value returned by prog is 
usually useless, unless (return..,) is used to return something 
meaningful. 



Inside a prog, you can put labels, to use for go-to' s: 

(defun bar 2 (x y) 

(prog () ;note the empty variable list 

(if (< X y)(go labl)) 
(print "X is not less than Y") 
(return nil) ;return "false" indication 

labl 

(print "so be it!") 

(return t))) ;return "true" indication 

In the special form £o, its operand (not argument) is a label to 
which to go, i.e., continue sequential evaluation of forms in the 
prog. Labels are rarely needed, due to the powerful if_ and 
do-forever constructs. 
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The or And and Special Forms , And not 



There are special forms for or-ing and and-ing predicate 
results: they are special because they stop evaluating their 
operands (from which arguments are produced) when they "know" 
their answer for certain: 

(if (and (not (= x 0)) 

{> (// 10 X) 5)) 
(print "Quotient too large.")) 

The not function inverts truth and falsity. The double slash 
indicates division, because slash is the escape character in 
Lisp. 



The and does not attempt to evaluate the second form within 
it if the first produces falsity. This prevents an error that 
would result if an attempt were made to divide by zero. 
Sequential execution and stopping at an intermediate result are 
defined and useful features here, as opposed to the logical 
•operators of, say, PL/I. 



The proqn , proql , and proq2 Special Forms 

Three more special forms are progn, progl, and prog2. To 
force sequential execution of forms and return the value of the 
last, use progn. For instance: 

(if (and (> x 3) 

(progn (print "Oh dear this is getting serious") 

(> y 5)) 
(print "Fatal difficulty"))) 

In the above, progn returns the value of its last form. Thus, 
the and tests whether x is greater than 3, and y is greater than 
5, before the "print" of "Fatal difficulty" is evaluated. The 
printing of "Oh dear..." occurs as part of the evaluation of the 
progn, but the and sees only the second value in the progn. The 
progn is used to force evaluation of the print form. 
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A proql is just like progn, except that it returns its first 
arguanent, evaluated, rather than its last. It must have at least 
two arguments. It is useful for saving some value that is 
subsequently going to be destroyed. The following form, when 
evaluated, interchanges the values of x and y: 

(setq X (progl y ; the value of y is obtained here, 

; and remembered as it is here, 
(setq y x) ) ) ; x is evaluated, and that value 

assigned, to y* The value of 
P setq form is that value. 

In the above, however, the value of proql is that value of y as 
it was before it was assigned into y, and now the outer setq 
assigns that to x» A proq2 is an older form of progl and is 
similar, except it returns its second argument. 



SYMBOLS 

Another type of data object in Lisp is called the symbol . 
Symbols are named data objects kept in a registry of symbols (the 
obarray), by Lisp, For current purposes, there is only one 
cynihoX of any name» Symbols are used in Emacs to represent 
buffer names, and various quantities associated with buffers. 
Lisp uses symbols to keep track of functions, and internally to 
keep track of global variables. 



To use a symbol in a program, give the name (the printname ) 
of the symbol preceded by an apostrophe (*). For instance, the 
form: 

(setq X *Brunhilde) 

assigns the symbol named Brunhilde to x. Note that this is 
different from: 

(setq X "Brunhilde") 
which assigns the string Brunhilde to x, and from: 

(setq X Brunhilde) 
which assigns the value of the variable Brunhilde to x. 
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LISP LISTS 



The final Lisp data type of importance in writing extensions 
is the cons (for construct), and the larger data type built out 
of it, the list « A cons is a block that relates to two {usually 
other) objects in the environment, known as its car and its cdr. 
The function cons, given two objects, produces a new cons, whose 
car and cdr, respectively, are the two objects given. For 
instance, if the variable x has a value of the string 
"Brunhilde", as above, then: 

(cons 7 X) 

produces a cons whose car is the number 7 and whose cdr is the 
string "Brunhilde", returning it as a value. The functions car 
and cdr can be used to obtain the car and cdr of a cons. If you 
set the. variable c to the result of the form (cons 7 x) above, 
then: 

(car c) 

produces the number 7 as a value. 



Usually, you make larger and larger structures out of 
conses, by setting up conses whose car and cdr are more conses, 
and so forth, until you have a large enough structure to 
represent all the values you need. The resulting construction 
serves the same purpose as a PL/I structure: its various parts 
have meaning assigned by the programmer. 



The most common construction of conses is the list. A list 
is defined as a chain of conses, each of which has the next one 
in the chain as its cdr, except the last one, which has the 
symbol "nil" as its cdr. A list built in this way of n conses is 
called a list of n elements , the elements being the n objects 
that are the cars of the conses. The cons at the head of the 
list is identified as being "the list": its car is the first 
element in the list, its cdr is the cons whose car is the second 
element of the list, and so forth. To construct a list of the 
numbers 2, 4, 5, and 7, in that order, and set the variable b to 
it, you would need: 

(setq b (cons 2 (cons 4 (cons 5 (cons 7 nil))))) 

(Note that the variable "nil" is peculiar insofar as its value is 
always the symbol "nil", thus you need not say 'nil.) 
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A function that simplifies the writing of such forms, for 
constructing lists, builds lists directly and accepts any number 
of arguments. It produces the same result as the type of 
construction shown above. It is called "list": 

(setq b (list 245 7)) 

To get the third element of. the list, once this form is 
evaluated, you could evaluate the form: 

(car (cdr (cdr b) ) ) 

(i»e,. , the car of the cons that is the cdr of the cons that is 

the cdr of the cons that is the value of b). Again, there are 

Lisp functions to simplify such constructions. The above form is 
equivalent to: 

(caddr b) 

In general, for up to 4 cars and cdrs deep, total, functions like 
cadr, cdar, caddr, cadar, and so forth, are provided (up through 
caaaar and cddddr). The first four elements of a list are gotten 
by car, cadr, caddr, and cadddr (it is a good exercise to work 
that through and verify why this is the case). 



When lists are printed out by Lisp, they are represented as 
a pair of parentheses around the printed representations of all 
of the elements, in sequence, separated by spaces. Thus, if Lisp 
printed out the list that was b's value above, it would appear: 

(2 4 5 7) 

A cons whose cdr is the symbol nil can always be viewed as a list 
of one item, and is so printed out by Lisp, unless it is in the 
process of printing a larger list of which the cons at issue is a 
chain-link. A cons whose cdr is neither nil nor another cons is 
printed with a dot preceding the cdr. Thus: 

(cons 'a *b) => (a . b) 

(cons 'a nil) => (a) ;a list of one element 
(cons 'a (cons 'b 'c)) => (a b . c) 

(cons 'a (cons 'b nil)) => (a b) ;list of two elements 
(cons 'a (cons (cons *b 'c)(cons 'd nil))) 

=> (a (b . c) d) ;list of three elements 
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Lists can be put into programs, by quoting them, as symbols 
are quoted: 

(setq bl '{this is (a list) (of lists))) 



Two functions are provided to redefine the car or cdr of an 
existing cons. They can be very dangerous if misused, especially 
if they alter a list as in the form above, which is written into 
a program as a constant. The rplaca function (replace car) and 
the rplacd function (replace cdr) each take two arguments* The 
first is the cons that is to be altered, and the second is the 
new car or new cdr, respectively. The returned value is the cons 
itself . 



Other list Primitives 

A variant of list, list*, is just like list except its last 
argument becomes the cdr of the last cons constructed. That is, 
list*, given n arguments (n > 2), constructs a list of its first 
n-1 arguments; the same as list given those n-1 arguments, but 
instead of the last cons having nil as its cdr, the nth argument 
is made its cdr. Thus, 

(list* 2 3 5 7) => (2 3 5 . 7) 

Note that: 

(list 2 3 5 7) => (2 3 5 7 . nil) 

=> (2 3 5.7) 

and: 

(list 2 3 5) => (2 3 5 . nil) 

=> (2 3 5) 



Another function for manipulating Lisp lists is append . It 
accepts any number of arguments, each of which is a list of zero 
or more elements, and constructs a list containing all the 
elements of all the lists, in order. Thus, 

(append '(a (b) c) '(able baker) '(2 3)) 
=> (a (b) c able baker 2 3) 



2-15 



CJ52-01 



The append function constructs a new list. A "destructive" 
form of append, called nconc , creates the result it returns by 
"patching" its input arguments to create a longer list, i.e., it 
changes the cdr of the last cons of each input list to be the 
first cons of the next list. The nconc function must be used 
with caution? e.g., it is always an error to give a constant 
(i.e., a quoted piece of list structure) as an argument to nconc. 



Another Lisp function for dealing with Lisp lists is 
reverse . Given a list, it returns a list with the same elements 
as the input list but in reverse, order.. The nreverse function is 
similar to reverse but, like- nconc, does its work by 
destructively modifying the input list.. 



A superlative method for writing code that builds list 
structure is provided by the Lisp "backquote" facility. The 
backquote facility is described in Appendix A. 



LISP MACROS 



List Structure as Code 

One of the most powerful features of Lisp is the ability of 
Lisp programs to manipulate Lisp programs easily. The internal 
representation of Lisp programs during compilation and debugging 
is that of Lisp lists. You may have noticed that Lisp lists 
strongly resemble pieces of Lisp programs. For example, the 
form: 

( setq X (■»- y z) ) 

is simply a printed representation of a list of three elements: 
the symbol setq, the symbol x, and the list (itself of three 
elements) of the symbols +, y, and z. Thus, a form is simply a 
piece of Lisp structure that is intended to be evaluated. In 
fact,, the eval function does precisely that; given a piece of 
list structure, i.e., a form, as an argument, eval evaluates it 
and returns the value of that form. Note how symbols represent 
both functions and variables, depending upon where they appear in 
forms. Symbols have bindings , which represent the binding of the 
variable represented by the symbol, and functional properties via 
which the associated function or code for a special form can be 
found. Thus, if the symbol (and thus variable) f is bound to: 

(setq X (+ y z) ) 

and y is bound to 3, and z is bound to 4, then evaluation of the 
symbol (variable) f would produce: 
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(setq X (+ y z)) 
a list of three elements. Evaluation of: 



(eval f) 

would pass that list of three elements as an argument to eval, 
causing its evaluation, which would cause x to have a binding of 
7 and return 1 as a result. 



In some sense, the basic action of Lisp is that of 
evaluation. However, user programs, other than Lisp debuggers or 
interpreters, rarely use the eval function. If you think you 
have to use eval (except sometimes in macros? see below), you are 
probably having difficulty with the concept of evaluation. 

Using Lisp Macros 

Lisp macros, allow a user to specify the translation of code 
with a syntax of his choosing into code representing the meaning 
he assigns to that syntax. A macro is defined just like a 
function, except that the word (symbol) "macro" (without 
quotation marks) appears between the function name and the 
parameter list. For instances 

(defun t-return macro (x) 

(append (cons 'progn (cdr x)) 
•(t))) 

defines a macro named t-return. When the compiler or interpreter 
sees a form whose car (i.e., where the function name belongs) is 
a symbol that has a macro definition (as above) associated with 
it, it passes the entire form to the macro as an argument , runs 
the macro (i.e., calls it with that argument), and reconsiders 
the result as if it were encountered in place of the original 
form. Thus, if a program contains a form: 

(and (> X 15) 

(t-return (setq flag nil)) 
(return x)) 

at the time this form is evaluated or compiled, in place of the 
second form, the form: 

(progn (setq flag nil) t) 

will be evaluated or compiled. This is because t-return has been 
defined as a macro; the function defined by t-return, when called 
with: 

(t-return (setq flag nil)) 
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as an argument, produces: 

(progn (setq flag nil) t) 

as a value. The fact that t-return has been defined as a macro 
causes the compiler to invoke t-return to translate the t-return 
form into its meaning , so that can be compiled or evaluated in 
its place. 



The backquote facility (see Appendix. A) is extremely useful 
for defining macros. Using backquote, you could define the macro 
above ast 

(defun t-return macro (x) 

(progn ,@(cdr x) t) ) 

See Appendix A for another example of a macro. Additional 
examples of macro definitions are contained in the 
e-macros.incl.lisp include file (after the first two pages if you 
dprint it) ► Bear in mind when studying them, however, that they 
reference internal Emacs variables and functions or embed certain 
knowledge that they are designed to hide. 



PRINTED REPRESENTATION OF LISP OBJECTS 

Lisp objects exist in the Lisp or Emacs environment. They 
relate to each other, and they denote each other. The calling of 
functions, whether built-in, Emacs-provided, or user-provided, 
creates new objects and changes the relationships among existing 
objects . 



Objects are symbols, conses, and strings in the Lisp 
environment; they are not parentheses and words on paper or in a 
buffer. However, you often need to obtain the printed 
representation of a Lisp object or generate a Lisp object based 
upon its printed representation. This is most commonly the case 
with numbers; in Emacs, the decimal-rep function obtains the 
printed representation of a decimal number as a string. 



The Lisp explode function creates a list of the 
single-character symbols representing the printed representation 
of the argument that was given. Passing such a list to the Lisp 
maknam primitive produces a symbol whose printname is that 
printed representation; that symbol is as good as a string for 
any purpose in Lisp or Emacs. Instead of maknam, the Emacs 
apply-catenats primitive can be used to produce a string and may 
be more efficient. 
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The conversion of numbers by explode is controlled by two 
global variables, base and *nopoint: base is the output radix, 
which is eight by default, indicating octal; *nopoint is nil, 
indicating that numbers are to be converted with a decimal point 
if base happens to be ten. Thus: 

(let ( (base 10. ) 

(*nopoint t)) 
(apply-catenate (explode x))) 

obtains the printed representation of the value of x, with 
numbers converted as decimal, without decimal points. 



read - from - st ring 

The Lisp read-f rom-str ing function constructs Lisp objects 
from strings (or symbols with a meaningful printname). Given a 
valid printed representation of a Lisp object, read-f rom-string 
recursively constructs (for lists), creates (for numbers or 
strings), or finds on the obarray (for symbols) the appropriate 
objects. Thus, if x is bound to the string "(a be)", the form: 

(read-f rom-string x) 

would produce as a value a list of the three symbols a, b, and c. 
In converting numbers with read-f rom-string, integers followed by 
a decimal point (e.g., 6., 27,, and 259., but not 5.0, which is 
floating point) are converted as decimal. Unpointed integers are 
converted as per the value (as radix) of the ibase global 
variable, which is normally eight. Thus, 

(let ((ibase 10.)) 

(read-f rom-string x)) 

converts the value of x with all unpointed numbers assumed 
decimal. / 
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SECTION 3 



WRITING EMACS EXTENSIONS 



Writing extensions is basically a matter o£ building new | 

functions out of the standard functions provided in the Emacs | 

Lisp environment. These new functions can be hooked up to keys | 

in the same fashion as standard Emacs functions, via the set-key | 

and set-permanent-key functions. | 



Many useful extensions can be made simply by stringing | 
together groups of Emacs requests. For instance, to go to the j 
beginning of a line, delete all whitespace there, go to the end 
of the line, do the same, and then return to the beginning of the 
line, you could type: 

'^A ESC \ -^E ESC \ '^A 

Alternatively, you could write a function, called shave-line 
here, to do the same: 



(defun shave-line {) 



(go-to-beginning-of-line) 
(delete-white-sides) 
(go-to-end-of-line) 
(delete-white-sides) 
(go-to-beginning-of-Iine) ) 



; keystroke functions take no args 



function 
function 
function 
ESC \ 
'^A 



hooked 
hooked 
hooked 



to 

to 
to 



'^A key 
ESC \ key 
key 



I 



Write this function into a file.. When in Emacs, type ESC X 

loadfile PATHNAME CR, to load it in as code. Then hook it up, 

perhaps by typing (when typing this, type the caret key for | 

not the control key): | 

ESC X set-key '^XA shave-line CR 

Thereafter, hitting '^XA (control X A) causes your new shave-line | 
function to be run. | 
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If you want a function that goes to the beginning of a line 
and deletes all words that start with "foo" from the beginning of 
the line, for example, you need to use Emacs conditionals and 
variables. 



(% include e-macros) 

(defun foodeleter () 

(go-to-beginning-of-line) 
(do-forever 

(if (looking-at "foo") 
(delete^word) 
(delete-white-sides) 
else ( stop-doing) ) ) ) 

The (%include e-macros) must be at the beginning of any file that 
uses the Emacs environment Lisp macros. The e-macros . incl . lisp 
file should be in your "translator" search path in order to do 
any Emacs extension development work. 



What this function does in essence is type ^A, and as long 
as the first three characters on the line are "foo", does an ESC 
D, followed by ESC \ to remove the whitespace after the word. 
When the first three characters are no longer "foo", it returns. 
The "looking-at" is an Emacs predicate (to be described in detail 
below) that tests whether a given string is to the right of the 
current "cursor". For this function and any others that you 
write, you could set a key as described above {^Xk for 
shave-line) . 

The code for the foodeleter makes no mention of printing, 
output, or displays because it does not need to. The screen or 
printing terminal is managed automatically by the Emacs 
redisplay. The display need never be thought about in coding 
Emacs extensions. 



USING EMACS REQUESTS IN EXTENSION CODING 

Many of the Emacs requests can and should be used in coding 
extensions, for example, go-to-end-of -line , forward-char, 
go-to-beginning-of-buf f er , delete-word and skip-over-indentation. 
Some requests, however, should not be used in extension code. 
For example, if you want to search for some string, you do not 
want to invoke string-search (^S), since that prompts the user in 
the minibuffer for a search string. The following table lists 
some important keystroke requests whose command names you should 
not use and gives alternative functions to use. 
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KEY DO NOT USE USE INSTEAD 

next-line-conunand next-line 
The next- line-command function is unnecessarily 
expensive in considering screen position, and handles 
numeric arguments. The next-line function always goes 
to the beginning of the next line. 

prev-line-command prev-line 
Same reasons as above. The prev-line function always 
goes to the beginning of the previous line. 

kill-lines kill-to-end-of-line 

delete-char (at eol) 
The kill-lines function is complex, has many cases, and 
handles numeric arguments. 

'^S string-search forward-search 

The forward-search function takes a string as a Lisp 
argument, does not prompt, moves the cursor if the 
search succeeds, and returns truth or falsity to 
indicate result. 

'^R reverse-string-search reverse-search 
Same as ^S. 

'^X^R read-file read-in-file 

The read-in-file function takes a Lisp argument for 
pathname, does not prompt. 

^Z^^ write-file write-out-f lie 
Same as '^X'^R. 

wipe-region wipe-point-mark 
Use local marks, see below. 

ESC W copy-region point-mark-to-string 

does not require modifying the user-visible mark or the 
kill stack. 

ESC / regexp-search-command regexp-search 

Same issues as ^S. Takes a Lisp argument, no slashes. 
Returns falsity if not found or moves cursor to after, 
and returns mark to before, matched string. Be careful 
to release this mark (see below). 

'^XB select-buffer go-to-or-create-buf f er 
Takes an argument, does not prompt. 

^X'^F find-file f ind-f ile-subr 

Takes an argument, does not prompt. 
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^L. redisplay-conunand full-redisplay 

redi splay-cur rent -window- relative 
Two separate functions, less dealing with numeric 
arguments. 



Requests that accept a positive numeric argument as meaning 
repeat that number of times, e.g., ^B, '^D, ^F, ESC B, ESC D, ESC 
F, ESC #, etc., are acceptable in extensions; they do not 
inspect their arguments.. They are invoked multiple times by the 
Emacs: listener if appropriate^ Requests whose names include the 
word "command"^ are usually not intended to be used in code. 



The value of a numeric argument, e.g., 5 in ESC 5 ^B, is 
available as the binding: of the global variable "numarg"; if no 
numeric argument is given, this variable is set to the symbol 
"nil" (not to be confused with the global variable nil, whose 
binding is; the symbol nil), which is the representation of 
falsity. 



The normal printing characters are bound to the self-insert 
function, which inserts the last physical character typed at the 
current point in the buffer. This is clearly unusable from code, 
if your desire is to insert text into the buffer. For this 
purpose, the Emacs environment provides the insert-string 
function, whose argument is a string to be inserted into the 
buffer at the cursor. As in typing in text manually, the cursor 
is left after the inserted text: 

(defun make-a-point () 

(go-to-beg inn ing-of -line) 
(insert-string "CASE IN POINT: ")) 



This make-a-point function, when invoked, goes to the 
beginning of the line, and inserts the string "CASE IN POINT: " 
in the buffer. The cursor is left after the inserted string. 



As used here, phrases like, "the cursor is moved around" or 
"a string is inserted" in a function, do not imply that the user 
watching the screen can see all these things happen. No action 
on the screen occurs until the entire function has finished 
running, at which time the screen is updated all at once, showing 
the cumulative effect of what has happened, regardless of how it 
happened. 
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MARKS AND THEIR MANAGEMENT 



Like the cursor, a mark is a conceptual pointer to the 
position between two characters in the current buffer. Marks 
remain between these two characters regardless of other 
insertions or deletions in the same buffer, even on the same line 
as the mark. Marks are valuable because regions of text in the 
buffer are specified as the extent between the current conceptual 
cursor, (the point ) , and a given mark. Marks are a type of data 
object in the Emacs Lisp environment, like strings, numbers, and 
symbols. The value of any variable can be made to be a mark. 
The value of several variables might even be the same mark. The 
words "the-mark" used in Emacs descriptions designate one mark 
that is the value of a global variable that many supplied 
functions know about. Emacs functions use many temporary marks. 



The set-mark, release-mark and wipe-point-mark Functions 

The set-mark function creates a new mark, which points to 
the current point in the current buffer. It stays around, and is 
updated by the editor, any time text is inserted or deleted in 
this buffer. This is expensive, so you must take care to 
discard, or release marks when you are done using them. This is 
done by giving them to the release-mark function. An example of 
a function which deletes three words and everything between them 
follows: 



(defun delete-three-words () 

(let ((temp-mark (set-mark))) ;make a mark in 

?a temp var. 
(do-times 3 (forward-word)) ;3 words forward 
(wipe-point-mark temp-mark) ;wipe out the stuff 

; between point and 
; where point was. 

( release-mark temp-mark ) ) ) 

The variable temp-mark is set to a mark representing the point at 
the time delete-three-words is entered. The "do-times" is a 
special form that repeats the evaluation of one or more forms a 
given number of times. Its syntax is: 



(do-times <HOWMANY> <F0RM1> <F0RM2> .. <FORMn>) 

The wipe-point-mark is a function that, given a mark, takes all 
the text between point at the time it is invoked and that mark 
(i.e., point at the time that mark was created) and deletes it 
from the buffer. It is pushed onto the kill ring, so that can 
be used to retrieve it. After the computation, the mark is 
freed, (for better performance). 
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The with-mark Special Form 



The sequence of setting a mark, using it, and releasing it 
is so common that a special construct in the Emacs Lisp 
environment is provided that takes care of all of this, including 
the creation of a temporary variable, so no prog or let is 
needed. It is called with-mark . The delete-three-words 
function, rewritten to use it, looks like this: 

(defun delete-three-words () 

(w^ith-mark m ;m is usually used for the name of a mark 
(do-times 3 (forward-word)) 

( wipe^point-mark m) ) ) 

The syntax of the with-mark construct is: 

(with-mark <MARKNAME> 
<F0RM1> 
<F0RM2> 

• * •- 
<FORMn> ) 

It means: "Where I am now, call that <MARKNAME>. Evaluate the 
forms <F0RM1> to <FORMn>, sequentially, returning the value of 
the last one as a value. Before returning anything, however, 
free the mark I made." 



Marks allow you to return easily to where you were at the 
time you started something. The following function truncates a 
line longer than 50 print positions, and handles backspaces and 
tabs properly: 



(defun trunc-50 () 
(with-mark m 

(go-to-end-of-line) 
(if (> (cur-hpos) 50.) 

(go-to-hpos 50.) 
( kill-to-end-of-line) ) 
(go-to-mark m) ) ) 



; remember where you started 

•dot is for decimal 
;default is octal 

;what does at not e.o.l. 
; return to where you were 



A function that tells you the horizontal position (on a 
dprint, not on the screen) of the current point is cur-hpos (the 
left margin is considered to be 0). It takes no arguments. The 
function go-to-hpos moves point to a position on the current line 
whose horizontal position is its argument. If the line is 
shorter than that horizontal position, the point goes to the end 
of the line and go-to-hpos returns nil. Otherwise, if it 
succeeds in moving point to the specified position, it returns 
the number gone to. Thus, this function can be used as a 
predicate. Therefore, the "if" in the above example could 
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instead be: 

(if (go-to-hpos 50.) 

( kill-to-end-of-line) ) 



The " (go-to-mark m)" above tells the editor to move the 
current point in this buffer to the point where it was at the 
time the mark called "m" was created. 



The save-excursion Special Form 

Although moving the editor's point to previously saved marks 
is extremely useful, you often use marks simply to return to the 
place where you were before you began a sequence of requests. 
This case is so common that a special mechanism is provided just 
for this: it is called save-excursion, and it takes care of all 
the problems of temporary variables and releasing the mark when 
done. The sample function trunc-50 receded to use save-excursion 
looks like this: 

(defun trunc-50 () 

(save-excursion 

(go-to-end-of-line) 
(if (> (cur-hpos) 50.) 
(go-to-hpos 50.) 
(kill-to-end-of-line) ) ) ) 

The save-excursion special form does the following: remembers 
where you are, via a mark saved in an internal variable, 
evaluates all of the forms within the save-excursion, and returns 
as a value the value of the last one. Before returning anything 
however, it moves the editor point back to where it was when the 
save-excursion was first entered, and releases the mark used to 
remember this place. 



If point were at print position 75 at the time trunc-50 was 
called, it winds up at position 50, even though the mark to which 
it wants to return points to what was at position 75. No error 
is indicated, or has occurred. Marks remain even if characters 
to the right or left of them are deleted. 



The save - excursion - on - error Special Form | 

The special form, save-excursion-on-error, is used in the | 
same way as save-excursion. It returns to the original point | 
only if an error occurs while executing the functions. | 
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KILLING, SAVING, AND MODIFYING IN EXTENSION CODE 



Most Emacs functions that delete text from the buffer save 
the text on the kill ring. Functions that you define that use 
these standard functions (such as delete-three-words , above), 
therefore, also save the deleted text. 



To prevent deleted text from being saved, wrap the code that 
will delete text in the without-saving special form. For 
example r 

(without- saving (wipe-point-mark m)) 

deletes- all the text between the current point and the position 
designated by the mark m without saving it on the kill ring. Any 
text deleted by an internal deletion primitive while the code 
contained within a without-saving special form is executing will 
not be pushed onto the kill ring. 



The without-modifying special form is similar to 
without-saving. It is used to enclose code that deliberately 
modifies read-only buffers, such as those used by the directory 
and buffer editors. For example: 

(without-modifying 

(go-to-beginning-of-line) 
(delete-char ) 
(insert-string "X")) 

might appear in a menu-type editing subsystem within Emacs to 
change the space at the beginning of some line to an X when the 
user selects an object for deletion. 



Text can be explicitly pushed onto the kill ring by the 
killsave-str ing function. It takes a single argument, which is a 
Lisp string or symbol, and pushes it in the usual way onto the 
top of the kill ring. 
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other functions which interface to the kill ring include 
kill-ring-top, kill-pop, and rotate-kill-ring. The kill-ring-top 
function returns the first item on the kill ring (as does ^Y). 
The kill-pop function returns, the first item on the kill ring and 
rotates the kill ring (as does ESC Y) . The first item becomes 
the last item, the second item becomes the first item, and so on. 
The rotate-kill-ring function just rotates the kill ring. 



CLEANUP HANDLERS 

You may have wondered, in the previous section, what happens 
if an extension encounters an error while executing, and never 
gets to release a mark it has set. When errors occur (for 
example, moving past the end of the buffer), Emacs aborts 
execution of request functions, returns to its listener, and 
beeps (as when a is performed). 
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The unwind-protect 



Special Form 



Since the releasing of marks is important, a facility like a 
cleanup-handler is needed to make sure that marks get released 
when code is aborted. There is such a facility in Lisp that is 
useful for many other things, too: save-excursion returns the 
cursor to the point at which it found it if aborted through; 
save-excursion-buf f er returns to the buffer where it found the 
editor if aborted through; all the mark-handling forms release 
their mark, and so forth. These Emacs-environment primitives use 
the cleanup-handler facility internally, so you need not worry 
about cleanup-handlers if you use them. However, occasionally 
(see the code for columnating the Emacs wall chart, for example) 
you must use cleanup-handlers explicitly. The Lisp form 
unwind-protect is the primitive cleanup-handler. Its syntax is: 

(unwind-protect 

<SUBJECTFORM> 

<CLEANUPF0RM1> 

<CLEANUPF0RM2> 

<CLEANUPFORMn>) 

The <SUBJECTFORM> is evaluated, and then <CLEANUPF0RM1> to 
<CLEANUPFOKMn> (any number of cleanup forms are permissible), and 
the value of the <SUBJECTFORM> returned. So far, unwind-protect 
is much like prog2 or progn. The difference, however, is that 
<CLEANUPF0RM1> to <CLEANUPFORMn> are executed even if the 
execution of <SUBJECTFORM> fails and aborts. Similarly, the 
cleanup forms are executed even if things like a return from a 
prog inside the <SUBJECTFORM> causes its execution to terminate 
prematurely. 



Thus, the cleanup forms are executed after every termination 
of the <SDBJECTFORM> , whether normal or abnormal. The following 
use of unwind-protect (which could be done in simpler ways, but 
is here for illustrative purposes) performs "complex-function", 
and returns the cursor to the beginning of the buffer, even if 
"complex-function" explodes: 

(unwind-protect 

(complex- function) 
(go-to-beginning-of -buffer) ) 

If you want more than one <SUBJECTFORM> , you should use progn to 
encompass them, and make your <SUBJECTFORM> this progn. 



Unlike Multics PL/I cleanup handlers, unwind-protect cleanup 
forms are executed upon normal termination of the subject form, 
too. 
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I The protect Special Form 



The e-macros special form, protect, can be used in place of 
unwind-protect . Its syntax is; 

(protect FORMl F0RM2 FCRM3 F0RM4 . . . 

Stalways CLEANUPl CLEANUP2,,.. 
^success SUCCESSl SUCCESS2.... 
£f allure FAILUREl FAILURE2 •.. ..) 

where: 
FORMi 

are forms to be evaluated^ 

CLEANUP! 

are forms to be evaluated after the FORMs, whether or 
not an error occurs in evaluating the FORMs, 

SUCCESS! 

are forms to be evaluated only if no errors occur in 
evaluating the FORMs, 

FAILUREl 

are forms to be evaluated only if an error does occur 
in evaluating the FORMs, 



I Any of the clauses &always, &success, or &failure can be omitted. 

I Forms that were written using unwind-protect, e.g., 

I (unwind-protect (progn FORMl F0RM2...) 

I CLEANUP! CLEANUP2 . . . ) 

I can now be written using protect as follows: 

I (protect FORMl F0RM2. . .&always CLEANUPl CLEANUP2,.,) 



USEFUL PREDICATES 

The following predicates in the Emacs environment are basic 
to all extension-writing; they are used to test various 
hypotheses about point, marks, and the buffer: 

(eolp) 

text line right before the newiine character. 
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(bolp) 

Beginning of line predicate. True if point is at the 
start of a text line, either before the first character 
of the buffer, or after a newline. 

( f irstlinep) 

First line predicate. True if point is on the first 
text line of the buffer. 

(lastlinep) 

Last line predicate. True if on last buffer line, 
which is the line after the last newline character, if 
there is one. 

(at-beginning-of -buffer) 

True if point is right before the first character in 
the buffer. 

(at-end-of-buf f er ) 

True if point is right before the newline on the last 
line of the buffer. You cannot go past it. 

(looking-at <STRING-VALUE>) 

True if <STRING-VALUE> appears in the buffer 
immediately to the right of point. Restriction: 
<STRING-VALUE> can not contain a newline character, 
except as its last character. 

(at-white-char ) 

True if the character to the right of point is a space, 
newline, or tab. 

(point>markp <MARK>) 

True if the current point is further in the buffer than 
the position defined by <MARK>'^ This is expensive, and 
should not be used casually in loops. 

(mark-reached <MARK>) 

True if the current point is up to or beyond <MARK> in 
the buffer. Intended for use in controlling 
character-by-character loops; it expects that point 
starts to the left of <MARK> and moves toward it. The 
function (order-mark-last <MARK>) can be used to switch 
point and mark if needed at the start of such loops. 
Does not terminate unless executed with mark and point 
on same line. 

(mark-at-current-point-p <MARK>) 

True if the mark <MARK> represents the same position as 
the. current point. 
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(mark-on-current-line-p <MARK>) 

True if the mark <MARK> represents a position on the. 
same line as the current point, 

(mark-same-line-p <MARK1.> <MARK2>) 

True if two marks that are arguments represent 
positions on the same line. 

( line-is-blank) 

True if current line is all blanks or empty. 

( emptY-buf fer-p < BUFFER- SYMBOL> ) 

True if the buffer identified by <3UFFBR-'SxMB0L> is 
empty. The form (empty-buff er-p current-buffer) can be 
used to test the emptiness of the current buffer. See 
below for a discussion of buffer symbols.. 

(at <QUOTED-CHARACTER> ) 

True if the character given, e.g., (at "$"), appears in 
the buffer immediately to the right of point. This is 
more efficient than looking-at for single characters. 
Note that: 

(at 

n 

is equivalent to (eolp) . Use the latter. (See also 
if-at. ) 

( bac k-at <QUOTED-CHARACTER> ) 

Same as at, but deals with the character to the left of 
the current point. See also if-back-at. 

(null-stringp <STRING-VALUE>) 

True if its argument is a zero-length string or a 
symbol with the zero-length printname. 

(yesp <STRING-VALUE>) 

Asks the user a yes-or-no question in the minibuffer, 

I namely, <STRING VALUE>; accepts yes, y, no, or n as 

answers and returns true if response is affirmative. 
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This function that trims from the left (Itrims) all the 
lines in the buffer demonstrates the use of these predicates: 



(defun Itrim-all-lines () 

(save-excursion ;be polite, restore point 

(go-to-beginning-of -buffer) 

(do-forever ?loop on lines thru buffer 

(do-forever ;loop thru chars on line 

(if (eolp) (stop-doing) ) ;stop at eol. 
(if (at-white-char ) (delete-char ) ?do the work 

else (stop-doing))) ;non-white char, next line 

(if (lastlinep) (stop-doing) ) ;guit when did last line 
(next-line)))) ;leaves you at b.o.l. 



WHITESPACE MANAGEMENT 

Neatly formatted editor output and displays, as well as 
program and document formatting, require good whitespace 
management. The following functions exist to deal with 
whitespace: 

skip-over-whitespace 

Takes no arguments. Moves point forward over all tabs, 
blanks, and newlines until a non-white character or the 
end of the buffer is reached. 



skip-back-whitespace 

Takes no arguments. Moves point backward over all 
tabs, newlines, and blanks until the character to the 
left of point is none of these, or the beginning of the 
buffer is reached. 

skip-to-whitespace 

Moves forward until character to right of point is tab, 
blank, or newline. Since last character in buffer must 
be a newline, there is no special end condition. 

skip-back-to-whitespace 

Moves backward until the character to the left of point 
is a tab, blank, or newline, or the beginning of the 
buffer is reached. 

delete-white-sides 

Deletes leading or trailing blanks from anything, or 
deletes space between words. 

skip-over-whitespace- in-line 

Same as skip-over-whitespace, but stops before the 
newline character at the end of the line (i.e., stops 
at the end of the line) if it gets that far. 
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skip-back-whitespace-in-line 

Same as skip-back-whitespace , but does not. proceed 
backward beyond the beginning of the line. 



You often need to generate whitespace to reach a given 
horizontal position (column), for tabbing and page layouts. The 
function whitespace-to-hpos performs this service; it generates 
tabs and spaces as appropriate, moving point until the horizontal 
position that is its. argument is. reached.. The following function 
moves: all lines: in the buffer seven spaces over, regardless of 
their original indentation, with, the right amount of tabs and 
spaces: 

(defun move-over-7 () 
( save-excursion 
(go-to-beginning-of -buffer) ;all do-for-all-lines 

(do-forever ;start like this., 

(skip-over-indentation) ;This is ESC M 
(let ((hpos (cur-hpos))) 

;let hpos be the curr. pos. 
(delete-white-sides) 

;close up all original space 
(whitespace-to-hpos (+ hpos 7))) 

;make just enough 
(if (lastlinep) (stop-doing) ) 
(next-line) ) ) ) 



A related need is to space to a given position, leaving a 
single space if you are already there or beyond. This is useful 
for producing columnar output where overlength fields must be 
separated (as '^X'^B does in its local display). The 
whitespace-to-hpos does not do this; it stops if it is far 
enough. However, format-to-col takes a single argument, a 
horizontal position to be spaced to. If the current point is 
already that far, it inserts a space. 



EXTRACTING TEXT FROM THE BUFFER . 

The function point-mark-to-string gets a Lisp string whose 
value is the string of characters between point and the mark that 
is its argument. To demonstrate, a function that finds a 
vertical bar (|) on a line, deletes it, and swaps the two 
line-halves around it is defined below. For instance, the line: 

An Indian with a zebra | never trips in the snow 

comes outs 

never trips in the snowAn Indian with a zebra 
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The function is: 

(defun swap-around-bar () 

(go-to-beginning-of-line) 

(if (not { forward-search-in-line "|")) . ;check for one~" 

(display-error "Hey, there is no 
(rubout-char ) ;what # does 

(with-mark m ;m in middle of line 

(go-to-end-of-line) 

(let ((temp (point-mark-to-string m))) ;get 

;middle 
;to end 

(without-saving (wipe-point-mark m) ) 

(go-to-beginning-of-line) 

(insert-string temp)))) ;put in text 



The forward-search-in-line is just like forward-search, except 
that it indicates failure if it cannot find its search string in 
the current line. If the vertical bar is not found, 
display-error lets you know and does a command-quit, i^G) , which 
stops the execution of this function. at once and returns to Emacs 
command level (see below). This is useful by itself to search 
for some string only in a given line. There is also a 
reverse-search-in-line, and a- regexp-search-in-line, which are 
similar in their relation to and ESC /. 



TALKING TO THE OSSR 

You cannot use the Lisp I/O system to print out messages 
and/or query the user. The Emacs redisplay manages the screen 
itself, entirely. Thus, you can not use "print", or "read", or 
other Lisp functions that you may be familiar with. 



A function called minibuf f er-print prints all the messages 
that Emacs outputs in the minibuffer screen area. It takes any 
number of arguments, which must be strings. The function 
decimal-rep is provided to convert numbers into strings for 
inserting them in the buffer or handing them to display-error. 
The following function counts the number of As in the current 
line: 

(defun a-counter () 

(let ((n 0)) ;initial count 

(save-excursion ;why not? 

(go-to-beginning-of-line) 
(do-forever 
(if (not (forward-search-in-line "A")) 

(minibuf f er-print "Found " (decimal-rep n) "As.") 
(stop-doing) ) 
(setq n (+ 1 n))))) ;count them. 
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The forward-search-in-line leaves the point to the right of 
what it finds (like ^S), so that it does not find the same 
occurrence the next time. 



To prompt the user for input in the minibuffer, use the 
function minibuf f er-response. It takes one, two, or three 
arguments. The first argument is the prompting string. The 
second is the character to be used to terminate minibuf fer input . 
It can be either ESC or NL; if not supplied, NL is the default. 
If the value of ESC is used, minibuffer input terminates on an 
ESC. If the value of NL is used (NL, not CR) , minibuffer input 
terminates on a carriage return. The third argument, when used, 
is a string to be inserted as the user's response. The user can 
edit this string ► Thusr 

(minibuf f er-response "Type new division name: ") 

returns the user's response to this question when he terminates 
it with a carriage return. The value of minibuf f er-response is a 
Lisp string. The carriage return does not appear in it, nor does 
the prompts 



The minibuf f er-response function sets a variable called 
last-minibuff er-response. If the ESC X opt 

remember-empty-response option is set off (it is on by default), 
last-minibuf f er-reponse is not set to blank when a blank response 
is given. 



To display an error message in the minibuffer and then abort 
execution of an extension, i.e., execute a command-quit C^G), use 
display-error. The display-error is like minibuf fer-print , 
except that it does not return, but aborts to Emacs top level 
immediately after printing its error message in the minibuffer. 
Like minibuf fer-print , it takes any number of string arguments. 



I You can clear out the entire minibuffer with the 

I minibuf fer-clear-all function. It takes no arguments. 
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Message Printing Functions 

Messages printed by minibuf f er-print are suppressed during 
keyboard macro execution, just as search strings are not 
displayed, and other gratuitous messages are suppressed. The 
following set of functions describes the repertoire of 

message-printing: 

display-error 

Prints a message in the minibuffer and aborts to editor 
top level. It is intended for use in error message 
printing. 

display-error-noabort 

Prints a message in the minibuffer and continues 
execution. This function is intended for reporting 
nonfatal errors such as "User not accepting 
messages. . . " . 

minibuf f er-print 

Prints a message in the minibuffer, but not during 
macro execution. This function is intended for use by 
extensions that print messages in the normal process of 
their execution, such as the line count from ^X=. For 
this function, as well as the others below, in 
multiline minibuffer situations, an appropriate line is 
chosen based upon availability of empty lines and 
several other criteria. 

minibuf fer-print-noclear 

Prints a message in the minibuffer (not during macro 
execution), but does not erase the previous contents. 
Output is appended to the last minibuffer line used. 

display-com-error 

Prints a message in the minibuffer and aborts to editor 
top level. Its first argument is a Multics standard 
error code. Its remaining arguments are character 
strings or symbols. See "Multics Error Table" below 
for the technique used to get error_table_ values into 
your program. 

display-com-error-noabort 

Prints a message in the minibuffer and continues 
execution. Its first argument is a Multics standard 
error code. 

minibuf fer-clear 

Clears out the last minibuffer line that was written, 
except during macro execution. This function should be 
used to clear out minibuffers written in by 
minibuf f er-print and minibuf fer-print-noclear at the 
end of subsystem invocation. 
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display-err or -remark 

Identical to display-error-noabort, except that the 
particular minibuffer line on which this remark is 
printed becomes the next one overwritten for any 
minibuffer remark or output. This function should be 
used for transient remarks (such as "Writing", 
"Modified", etc. )f that you wish to remove from the 
screen as soon as possible. 

command-quit 

Aborts ta top level (or to the minibuffer if one is 
being entered) and rings the terminal bell. Execution 
of the current extension code is irretrievably stopped. 
This function is used by display-error and 
display-com-error internally? since it is better to 
print a message when an error occurs, generally use 
these latter two functions instead of command-quit. Do 
not use command-prompt-abort (what invokes) to error 
abort out of code, since it would abort minibuffers as 
well. 

ring-tty-bell 

Rings the terminal bell (or beeper) with no other 
effect. All. error aborts out of code, such as those 
caused by display-error and display-com-error, do this 
by default.. 



VARIABLES 

Many groups of Emacs requests need global variables to 
communicate among themselves and the functions they call. A 
global variable is a Lisp variable that is not the parameter of 
any particular function; its value can be accessed or set by any 
function. Some of the global variables in Emacs are highly 
user-visible, for example, "fill-column", which contains the 
column number of the fill column as set by ^XF, and used by the 
filling requests and fill mode. Similarly, the character string 
that is the comment prefix is the binding of the global variable 
"comment-prefix". Extensions often need global variables to 
communicate among their parts. 



Normally, global variables in Lisp are accessed just like 
other variables, i.e., those that are parameters of functions or 
prog or let variables. For instance, a function to set the fill 
column to 30 if it is over 40, might contain the code: 

(if (> fill=column 40.)(3etq fill-column 30.)) 
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when a global variable is used in your program, say one 
named "my-global", the "declaration" 

(declare (special my-global)) 

must appear in the program before its first use, to tell the 
compiler about this "special" variable (the Lisp term for a 
global variable). The e-macros include file declares many of the 
provided global variables, which you need not declare. 



defvar 

An even more powerful way to declare your own global 
variables is provided by the defvar declaration/special form. In 
its simplest form: 

(defvar my-global) 
is equivalent to: 

(declare (special my-global)) 
but is simpler and more mnemonic. 



Use defvar to specify an initial value to be assigned to the 
global variable at the time the program is loaded. This value 
will be assigned only if the variable has not already been 
assigned a value; this makes it ideal for user-settable options. 
For example : 

(defvar magic-mode-debug- flag nil) 

not only declares magic-mode-debug flag special, but gives it a 
value of nil (remember that the binding of the variable nil is 
the symbol nil) if the user has not assigned a value to it before 
loading the magic-mode program, where this declaration presumably 
appears. 



PROVIDED GLOBAL VARIABLES 

You have already encountered som.e of the global variables in 
Emacs during the introduction to Lisp; for example, the global 
variables t and nil that contain the standard indicators of truth 
and falsity. There are also global variables whose values are 
symbols whose printnames (see "Character Dispatching") are 
hard-to-type characters. Most of the interesting global 
variables in Emacs are associated with given buffers, such as 
variables containing the pathname and comment column (this is 
discussed below). 
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There are, however, a few truly global variables that Emacs 
uses. Here are two of them you might need to use. You need not 
declare them special, since they are declared in the e-macros 
include file. 

env-dir 

a string that is the pathname of the directory 
containing all. the Emacs library programs. 

process-dir 

a string that is the pathname of; your; process 
directory.- 



Per-Buf fer Variables 

The global variable situation is complicated by the fact 
that editing activity is usually local to each buffer. That is, 
if a set of global variables contains a set of values about what 
is being edited, it usually pertains to what is going on in only 
one editor buffer. If you switch to a different buffer, and use 
the same editor facility, you do not want to use or change the 
values of those global variables that pertained to activity in 
the other buffer.. At first, this would seem to make global 
variables unusable, because all functions would have to keep 
track of what buffer they are talking about before using any 
global variables, and therefore maintain several sets of them. 
Fortunately, it is a lot easier than that. The buffer-switcher 
in Emacs saves and restores values of global variables as buffers 
are switched, if you tell it what variables you want so saved and 
restored, when the buffer you are operating in is exited and 
reentered, respectively. Such a variable is called a per - buf f er 
variable , and the act of telling the buffer-switcher about it, 
thereby associating its current value with this buffer, is called 
registering it. Once a variable has been registered in a given 
buffer, the functions that use it can assume that its value will 
be what it last was in that buffer whenever the editor enters 
that buffer. Another term for a per-buffer variable is a local 
variable . The following two primitives exist for registering 
local variables; there are no primitives for setting or 
retrieving their values, because the whole point of this 
mechanism is to allow them to be accessed as normal Lisp 
variables. 

register-local- variable 

Called with one argument, the symbol whose name is the 
name of the local variable you wish to register. 
Registers it in the current buffer, if not already 
registered there, and the variable initially inherits 
its "global value". If registered, its value is left 
alone. If it has no global value, it acquires the 
symbol "nil" as its value if this is its first 
registration in this buffer. 
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establish-local-var 

Just like register-local-variable, but takes a second 
argument, a default value to be initially assigned to 
the variable the first time it is registered in this 
buffer, if it has no global value. 



The global value of a per-buffer variable is the value it 
has in buffers in which it is not registered. It is this value 
that is set if you set this variable while in a buffer in which 
it is not registered, A local variable "inherits" its global 
value when it is first registered in a given buffer. For 
variables that have no global value (i.e., were never assigned 
one), establish-local-var can be used to provide default 
initialization. 



EXAMPLE OF LOCAL VARIABLES 

Three functions that maintain a "problem count" in a given 
buffer are started up by typing ESC X monitor-problems CR. Once 
started, use ^XP to count a problem, and '^XR to report the number 
of problems noted: 

(defun monitor-problems () ; command-level function 

(set-key ' ^XP ' note-a-problem) ;set the keys needed, 
(set-key *^XR 'report-problems) ;only in this buffer 
(establish-local-var 'problem-count 0)) ;register the 
; local var, initial value 0 here. 

(defun note-a-problem () ;executed on '^XP 

(setg problem-count (+ 1 problem-count))) ;Increment the 

; variable 

(defun report-problems () ?on '^XR 

(minibuf f er-print "There have been " 

(decimal-rep problem-count) 
" problems in this buffer.")) 



By calling establish-local-var on the symbol 
"problem-count", the programmer here has ensured that the 
problem-counts in each buffer in which he counts problems will be 
maintained separately. 
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REGISTERED VARIABLES 



The following per~buffer variables are automatically 
registered by the editor. Their values can be inspected or set 
in extension code* 

buf f e r-mod i f i ed- f lag 

Contains t or nil, indicating that this buffer has or 
has not been modified since last read in or written. 
Set automatically by the editor. Modification of a 
buffer executed within the special formt 

(without-modifying <forml><f orm2>, . .<formn>) 

does not set this flag. 

read-only-flag 

Contains t or nil indicating whether or not this is 
read-only buffer.. The editor does not set this flag; 
it is set only by extensions. An attempt to modify the 
text in this buffer produces an error and a quit to 
editor command level if this flag is on and 
buf fer-modif ied-flag is off (nil). The buffer can be 
modified, however, by functions executed from within 
extension code within a "(without-modifying ...)". 

fpathname 

Contains the full Multics pathname associated with this 
buffer by the last file read or written into/out of it, 
or by find-file. It is nil if there is none. Changing 
it from extension code modifies or "forgets" the 
pathname as you set it. 

der-wahrer-mark 

Contains the mark associated with the user-visible mark 
that ^X'^X and other related requests see. Is nil if 
the user set no mark in this buffer. Do not set this 
variable; call set-the-mark to do so. 

cur rent-buf f er-mode 

Contains the major mode in effect in this buffer. The 
value is a symbol. To state that a major mode of your 
construction is in effect in a buffer, simply set this 
variable. 

comment -column 

Contains the comment column, measured from 0. 

c omme nt— prefix 

Contains the string, which can be a null string, that 
is the comment prefix. 
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tab-equivalent 

Contains the number of spaces for a tab. Initialized 
to 10., the Multics standard, this can be set- either in 
code or by ESC ESC to edit code from other operating 
systems. The redisplay obeys this variable too, but 
not in two-window mode. 

buffer-minor-modes 

Contains the Lisp list of symbols representing the 
minor modes in effect in this buffer. 

MODE HOOKS 

Emacs provides a set of global variables called mode hooks . 
Most major modes currently have mode-hook variables. The 
mode-hook variable for a major mode allows a user to run his own 
code every time a certain major mode is entered. For instance, a 
user might want to set certain key bindings every time he uses 
PL/I mode. The mode-hook variable is generally named 
XXX-mode-hook for XXX mode. The following are currently defined: 



MODE 


NAME OF HOOK VARIABLE 


RMAIL 


rmail -mode -hook 


MAIL 


ma i 1-mode-hook 


PL/I 


pll-mode-hook 


FORTRAN 


f ortran-mode-hook 


ALM 


aim-mode-hook 


LISP 


1 i sp-mode-hook 


LDEBUG 


Idebug-mode-hook 


TEXT 


text-mode-hook 



To use the mode hooks, write a function that is to be 
executed every time the mode is entered. (This function is 
usually defined in the Emacs start_up.) For example: 

(defun Mike-pll-mode-hook( ) 

(set-key "ESC-+" ' search-f or- journalization-notice) ) 

In the start_up, set the variable pll-mode-hook to the symbol 
Mike-pll-mode-hook. This is done with a statement of the form: 

(setq pll-mode-hook 'Mike-pll-mode-hook) 

Thus, every time Mike enters PL/I mode, the function 
Mike-pll-mode-hook is run, binding ESC + to Mike's 
journalization-notice finder. 



Modes use defvar to assign nil to their mode-hook variables 
if the user (via his start_up) has not assigned something else. 
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I other User Hooks 



Several additional hooks for functions to be called at 
special times are available. In order to use them, write your 
own function, of one argument, and use setq to set the 
appropriate hook to the name of your function. The one argument 
passed is the name of the hook being invoked. These include: 

buffer-creation-hook 

called when a buffer is created.. 
buffer-destruction-hook 

called when a buffer is destroyed, 
buffer-entrance-hook 

called when a new buffer is selected, 
buffer-exit-hook 

called when a buffer is left, 
close-line-hook 

called when the user moves to another line. 



LARGE SCALE OUTPUT 

Output of multiline information, or information longer than 
about 60 characters, should not be done via minibuffer printing, 
but via the local - display , or printout facility. This is the 
facility with which buffer listings, global searches, apropos, 
and other requests display their output. On video terminals, it 
displays lines at the top of the screen, asking for "MORE?" as 
each screen fills up. At the end of the local display, it waits 
for the user to type the next Emacs request, and then restores 
the screen. On printing terminals, the data is simply printed 
line by line, with no "MORE?" processing or pausing at the end. 
The local display facility is an integral part of the Emacs 
redisplay. 

Three functions used in generating local displays are: 

in it-local-displays 

Is called with no arguments to start a local display. 

It sets up the necessary redisplay mechanism, 

initializing it to the top of the screen. 

local-di splay-generator 

This function is called with a string, whose last 
character must be a newline, and displays it as the 
next line (or lines, if continuation lines are 
required) of local output. If you do not have a 
newline at the end of your string, calling 
local-display-generator-nnl instead provides one 
automatically. There must be no embedded newlines in 
strings for local output. A null string causes an 
empty line. 
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end-local-displays 

Finishes a local display, restoring the screen. Causes 
the next redisplay to be suppressed, so the local 
display remains visible on the screen. 



The sequence of calls: 

( init-local-displays) 

(local-display-generator {-nnl} .,•) ;perhaps many 

; times 

( end-local-di splays ) 
correctly produces a local display. 



The best way to generate a well-formatted local display is to 
set up a temporary buffer (see "Manipulating Buffers" below), 
build some text in it, and display its content, in part or in 
whole, as a local display. Three functions are provided to 
facilitate this: 

local-display-current-line 

Does a local-display-generator on the current editor 
line in this buffer. 

display-buff er-as-printout 

Does an init-local-displays, and displays all lines of 
the current buffer as local output. It does not do an 
end-local-displays; you have to do that yourself, 
hopefully after you have gotten out of your temporary 
buffer and cleaned up whatever else you had to. 

view-region-as-lines 

Displays the entire point-to-user-visible-mark as local 
display, making all the necessary calls, including 
end-local-displays. 



While in a function that has a local display in progress, 
you must never call the redisplay (see "Calling the Redisplay" 
below), or call minibuf-response or any other function that 
causes redisplay, for that instantaneously restores the screen 
contents to the windows on display, obliterating the local 
display in progress. 
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The following function locally displays all lines in the 
buffer that contain the string "defun": 

(defun look-for-defuns( ) ;use ESC X look-f or-def uns CR 

(save-excursion ; remember where you are. 

{ go-to-beg inn ing-of -buffer) 

{ init-local-displays) ;set up for printout, 
(do-forever ;loop the buffer 

{it (forward-search-in-l.ine "defun") ;look for 

; "defun" 

Clocal-display-current-line) ) ;cause printout 

;of it 

(if (lastlinep) (stop-doing) ) ;check for BOB. 
(next-line))) ;Go to start of 

;next line 

(end-local-displays)) ;wait for user, and 

;next request 



A special form, display-as-printout , is available. It 
generates a new buffer, executes your contained forms, displays 
the whole buffer as local display, destroys the buffer, and 
returns. Its syntax is: 

(display-as-printout 
<F0RM1> 
<F0RM2> 



<FORMn>) 



MANIPULATING BUFFERS 

Often, the easiest way to do string processing in the editor 
environment, i.e., handle strings, catenating, searching, etc., 
is to use the primitives of the editor itself, since it is a 
string-processing language. To do this, temporary buffers are 
necessary. To create a buffer, you should use the primitive 
go-to-or-create-buf f er (what ^XB uses), which goes to a buffer 
associated with the symbol you give it as an argument. 



Most symbols are kept in a registry: this registry is 

called the obarray , and there is only one symbol of any given 
name in it. A symisol registered in the obarray is said to be 
interned. Only one interned symbol named "joe" exists, but you 
can create many uninterned symbols named "joe". If you refer to 

a cvmHol namoH "too" in a nrnrrram Vinwovor hu cawinrr "'-in/a" wQii 

always get the interned one. 
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A major feature of symbols in Lisp is that they can be given 
properties , arbitrary user-defined attributes. These attributes 
are catalogued "in" the symbol via indicators , symbols that 
indicate what property you want. The Lisp functions "putprop" 
and "get" store and retrieve properties. 

(putprop 'Fred 'blue 'eyes) ;Gives the interned symbol 

; named "Fred" an "eyes" 
;property of "blue". 



(get 'Fred 'eyes) ; retrieves the property under the 

; indicator "eyes", and thus returns 
;the interned symbol "blue". 



In Emacs, symbols represent buffers. All of the information 
associated with a buffer, is catalogued as properties of some 
symbol whose name is the name of the buffer. Thus, it is 
possible to have two buffers of the same name, which would imply 
that of the symbols representing them, only one is interned. The 
'^XB request always uses the interned symbol of the name given; 
that is why you can ^XB back to an existing buffer instead of 
creating a new one each time. 



Creating a Temporary Buffer 

To create a temporary buffer, you must first create an 
uninterned symbol, to make sure that you are not going to switch 
to a buffer that is already real. To do this, you give a string 
to be used in naming the symbol to the Lisp cliche: 

(maknam (explodec "A string")) 

The explodec blows the string apart into a Lisp list of 
characters; the maknam builds a symbol out of it. The value of 
this form is the new symbol. You can then go to a (guaranteed) 
new buffer of that name, i.e., 

(go-to-or-create-buf f er (maknam (explodec "A string"))) 

and the global variable "current-buffer" will have that symbol as 
its value. A temporary buffer is one that is destroyed 
automatically by the editor upon switching out of it. To make a 
buffer temporary, all you have to do is give the symbol that 
represents it (the "buffer symbol") a "temporary-buffer" property 
of the symbol "t". This can be done by the Lisp form: 

(putprop current-buffer t 'temporary-buffer) 
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(The variable "t"' is always bound to the symbol "t"). Once this 
has been done, you must be careful not to switch out of this 
buffer until you are done with it. If your code involves 
manipulating many buffers, some of them temporary, you must give 
the temporary buffers their temporary-buffer properties at the 
end of your manipulations. 



A better way to do this is via the- set-buffer-self-destruct 
function.. Calling: this function upon the buffer-symbol, as 
belowr 

( set-buffer-self-destruct current-buffer) 

schedules the buffer for deletion as soon as the buffer is 
exited. Using this, you find out sooner if you mistype this 
function name than if you mistype the temporary buffer property. 



When a new buffer is created, i£ contains one line, which 
consists of a linefeed only- There are no truly empty buffers in 
Emacs. The predicate empty-buff er-p can be applied to a buffer 
symbol to determine if that buffer is in this state. When 
buffers are switched, all information related to the old buffer 
is stored as properties of the buffer symbol: this includes not 
only the local variables registered in that buffer, but the 
location of point, the user-visible (and all other) marks, etc. 
Thus, when buffers are switched back and forth, the cursor 
retains its position in each buffer (as can be seen while 
editing), although the redisplay might choose to display a screen 
differently after visiting another buffer and coming back. 



Some applications require making a nontemporary buffer, 
putting some text in it, and going back there on occasion. 
Therefore, you might want to go into a nontemporary buffer of an 
interned buffer symbol: 

(go-to-or-create-buf f er * name-and-address-buf f er ) 

or perhaps keep a global ( not per-buffer) variable that you set 
once to an uninterned symbol: 

( setq name-and-address-keep-track 

(maknam (explodec "Name and Address Buffer"))) 

and switch into it by saying: 

/ ^ A MB ^ A ^Aa** W «*« A M> ^ M ^ M ^ A mm ^ «• ^ 1» \ 
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The function buffer-kill can be called with a buffer symbol 
to destroy a buffer. The function destroy-buf f er-contents (of no 
arguments) can be called to reduce the current buffer to a single 
"empty" line (buffer contents are not pushed onto the kill ring). 



dont - not ice - modi fied - buffer 

When you create features and modes that interact with the 
user either by placing "results" in a buffer, accepting user 
input typed "into" a buffer, or both, these buffers will be 
"noticed" when the user leaves Emacs, with the standard query 
about modified buffers. However, you can prevent guit-the-editor 
(what ^X^C invokes) from taking notice of a given buffer even 
though that buffer is modified. This is done by marking the 
buffer concerned with the dont-notice-modif ied-buf f er function. 
It takes a single argument, which is the buffer symbol of the 
buffer concerned. 



Variable for Buffer Manipulation 

The following two variables are relevant to buffer 
manipulation : 

current-buffer 

The value of this variable is the buffer symbol of the 
current buffer. Do not change it, or incorrect 
operation results. Use go-to-or-create-buf i er . 

previous-buffer 

The value of this variable is the buffer symbol of the 
last buffer, which is returned to when -^XB CR is typed. 
It is acceptable to setg this variable. 



The go-to-or-create-buf fer function accepts a buffer-name of 
""as meaning go to that previous buffer. 



The save-excurs ion-buffer Special Form 

The special form save-excursion-buf f er is invaluable when 
writing functions that switch buffers. It provides for 
remembering which buffer you were in, and switching back to it 
when you are done. It also saves and restores the state of 
"previous-buffer". The save-excursion-buf fer is like 
save-excursion; it executes its contained forms while pushing the 
buffer-state of the editor on an internal stack, and returns the 
value of the last form within it. 
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The following program, when invoked after typing somebody's 
name (say you hook it up to a key), follows it with his title in 
parentheses. Assume the file >udd>FamNam>personnel_data looks 
like this: 

Washington, G, ^Lumberjack 
Duck, D. =Pe.ssimi.st 
Nietzsche, F. =Existentialist 
Mouse, M. ^Optimist 
Si:Senhower, D. D., »Goif.e.r 

(.de£urt insert-persoTi-tltle (.) 

(iet ( (inanie ( save-excursion r-save guy's point 

(skip- back -whitespace) ;g.et to end of word 
(witii-mark m ;jn « end of word 

(backward-word) ;g.o to beg. of wd, 

( ca-tenat.e ( pod nt -mar k- to- str ing m ) 
","))))) 

; return the word with a after it. 
(insert-string ; insert 

(catenate (" ;qpen par en and sp 

(save-excurs ion-buffer ;save the old buff 

( go-to-or-create-buf fer ' name-pos it i on- records) 

;go to stuff 
(if (empty-buff er-p current-buffer) ;read it 

;once 

(read-in-f ile ''>udd>FamNam>personnel_data" ) ) 



(go-to-beginning-of-buf f er ) 
(do-forever 
(if (loo king- at name) 



set up for search 
scan lines 
Is point at 
"name, "? 
look for the =. 
get to the end. 



(forward-search "-") 
(return (with-mark n 

(go-to-end-of-line) 
(point-mark-to-string n) ) ) ) 
(if (lastlinep) (return "???")) ;couldn't 

;find him 

(next-line)) ;move on 

) "))))) 
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This function picks out the name you just typed by skipping 
back over whitespace, and picking up all between there and the 
start of the previous (current) word. It then inserts, between 
parentheses, the portion of that line of the data file that 
contains the sought name at. its front after the equals sign. The 
buffer name-position-records is read into once, and contains the 
data file thereafter. 



The initial save-excursion remembers the user's point 
location while the word is collected. The save-excursion-buf f er 
remembers what buffer and where in it all its modes, local 
variables, etc., are, while you operate in the data file buffer. 



The function catenate is a valuable one in the context of 
Emacs; it takes any number of strings (or symbols, whose 
printname will be used), builds a string by catenating them 
first-to-last, and returns it. " 



Another useful function in this context is apply-catenate , 
which takes as an argument a list of any number of strings or 
symbols and builds a string by catenating the strings and names 
of the symbols, first to last. 



CALLING THE REDISPLAY 

The Emacs redisplay decides what lines of the current buffer 
should be shown on the screen, determines how to modify the 
current screen to show the contents of those lines, and updates 
the screen in an optimal manner. It is called by the editor 
whenever there is no more input available. It is very simple to 
call. It takes no argxjments, i.e., you just say: 

(redisplay) 



The redisplay does not know or care by what means the buffer 
was modified; if you delete several words with ESC D, '^D, or '^W, 
it is all the same to the redisplay, and it acts similarly in 
updating the screen. Normally, the extension writer need not be 
concerned at all about the redisplay. A major feature of Emacs 
is that only the total effect of a complex manipulation is 
displayed, not every small operation that the manipulation used 
to achieve its effect. 
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In some situations, however, it is. advantageous to call the 
redisplay explicitly from extensioa code. One example is a 
function that takes a, tremendous amount of computer time and 
might wish to update: the screen every, so often as it finishes 
some major section. Yoa do not tell the redisplay what to 
display or how to, display it; it displays some excerpt of the 
current buffer that contains the current line, and shows the 
cursor where the current point is. If you call it during a 
buffer excursion, i.e.., while in some special buffer in a 
function, it displays that buffer around its "point" ► As soon as 
that function reiturns^ ta editor command level, the screen is 
overwritten with the arigsinal buffer's lines* Thus, calling 
redisplay is not to be$ considered cl SiUbstitute for local 
displays- 



The most common need, for calling redisplay is in functions 
that add text (or change text) on a. line, and move to another 
line. For example, the electric semicolon of electric PL/I mode 
adds a semicolon to the current line and moves, to the next. On a 
printing terminal, the user would never see the semicolon unless 
special action were taken* The text in the buffer would indeed 
be right, but by the time the next redisplay occurred (the 
electric semicolon request returned), the, editor would be off 
that line, and thus would display the next line, where the 
electric semicolon request left it. While this is correct, the 
printing terminal user looking at his type-in would, with, some 
validity, complain that "all the semicolons seem to be missing". 
Thus, the electric PE/I semicolon request calls the redisplay 
immediately after it executes "(insert-string ";")". 



The following is a function for a "card-numbering FORTRAN 
mode", which when invoked (perhaps hook it up to CR) puts a 
sequence number in column 72 (71 from 0) and goes to column 7 of 
the next line. It must call the redisplay so that, on a printing 
terminal, the card numbers get shown: 



(defun f ortran-next-line () 

(whitespace-to-hpos 71.) 
(insert-string (decimal-rep cardno)) 

(setq cardno (+ 1 cardno)) 

(redisplay ) 

(new-line) 

(whitespace-to-hpos 6,)) 



go to col 72. 
cardno is a local 
buffer var 
up the next 
card number 
let printing 
user see. 
get to 
next line 

6 rel = card col 7. 
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Another commonly called redisplay function is 
full-redisplay , of no arguments, which clears and rewrites the 
screen, as with '^L with no arguments. 



Positioning Text on the Screen 

Emacs usually positions text on the screen automatically. 
When the cursor is moved to text already on the screen, it is 
simply repositioned on the current screen. If the text is not 
already on the screen, Emacs usually centers the line containing 
the text positioned to in the current window. Sometimes, it is 
desirable to have other than this default action. You may wish, 
say, to position some text onto the top of the screen from 
extension code; this is what ESC 1 '^L does. The 
redisplay-current-window-relative function is what 

redi splay-command {^L) calls when given an argument. Thus, 

(redisplay-current-window-relative 3) 

redisplays the current window with the current line of the 
current buffer on line 3 of the window. 



EIS TABLES 

The Emacs environment provides a facility for utilizing the 
sophisticated Multics processor instructions for scanning for 
characters in, or not in, a particular set of characters. These 
operations correspond to the PL/I "search" and "verify" builtins. 
The word requests operate using these facilities. 



A set of characters is represented by a charscan table, a 
compound Lisp object occupying about 200 words of storage. You 
can get a charscan table by giving a set of characters, as a 
string, to the function charscan-table. It returns a charscan 
table representing that set of characters: 

(setq number-verify-table (charscan-table "0123456789+-")) 



Functions Using the Charscan Table 

Given such a table, there are a set of functions that can be 
called to utilize it to search for characters in or out of that 
set, backward, forward, whole buffer, or only one line. All but 
the last of the following functions take one argument, a charscan 
table representing a set of characters (called S here). They 
return nil (falsity) if they hit the end of the buffer or line 
(as appropriate) without finding what they are looking for. If 
they succeed, they move point and return a truth indication. If 
they fail, they do not move point. 
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search- for-first-char set-line 

Scans current line forward from point. Success is 
stopping to the left of a character in S. 

search-for-first-not-char set-line 

Same as above, but success is stopping to the left of a 
character not in S. 

search-back- first-charset-line 

Scans current line backward from point. Success is 
stopping to the right of a character in S.. 

search— back—f i rst— not-char se t— 1 ine 

Same- as search-back-f irst-charset-line , but success is 
stopping to the right of a character not in S, 

search-char set- forward 

Scans the buffer from point to the end of the buffer. 
Success is stopping to the left of a character in S. 

search-char set-backward 

Scans the buffer backward from point to the beginning 
of the buffer. Success is stopping to the right of a 
character in S. 

search-not-charset- forward 

Scans the buffer forward from point to the end. 
Success is stopping to the left of a character not in 
S. 

search-not-char set-backward 

Scans the buffer backward from point to the beginning 
of the buffer. Success is stopping to the right of a 
character not in S. 

char set-member 

A predicate; takes two arguments: a character and a 
charscan table. The character can be a single 
character string, a single-character-named symbol, or a 
numeric ASCII value. Returns true if the character is 
a member of the set of characters represented by the 
charscan table. 



The following function finds the first nonnumeric character 
on the line it is invoked on: 

(defun find-first-non-numeric () 

(establish-local-var numscan-table nil) ;does 

;var exist 

(if (not numscan-table) ?if nil, i.e., not init yet, 

(setq numscan-table (charscan-table "0123456789"))) 
( go-to-beg inn ing-of -line ) 
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(if (not (search-for-f irst-not-charset-line 

numscan-table) ) 
(minibuf f er-print "Line is O.K.!"))) ;failure 

;is all are 
;in charset 



OPTIONS 

The Emacs option mechanism provides for user-settable 
•variables in the Lisp environment. The only difference between 
an "option" and any other global Lisp variable in the editor 
(basic or extended) is that the options are listed at the 
user-visible level by typing ESC X opt list CR, and can be set or 
interrogated via the opt request. The option mechanism also 
provides for checking that numeric variables stay numeric, and 
that variables restricted to "t" or "nil" as values stay 
restricted to those values. 



Thus, options can control per-buffer or truly global 
variables; the option mechanism imposes no restraints upon the 
dynamic scope of the variables managed by it. The option 
mechanism also provides for a default global value of variables 
it manages. 



A global variable is registered with the option mechanism by 
invoking the function register-option upon the Lisp symbol that 
represents (has the name of) that variable, and its default 
global value. If that value is a number, the option mechanism 
restricts the variable's value to numbers? if it is one of t or 
nil, the option mechanism restricts its values to t or nil (which 
you indicate as "on" or "off"). 



The choice of whether a variable should be made an official 
option or not depends upon whether or not you want the user to 
see it when an "opt list" is done, and whether finer control than 
that provided by the option mechanism over the values assigned to 
it is necessary. It is acceptable to register an option the 
first time some code is executed? only then does it appear in the 
option list. It is usual to have forms invoking register-option 
at "top-level" in a file full of code,- i.e*, outside of any 
function. Such code is executed when the code is brought into 
the editor environment. 



The following code registers an option describing default 
paragraph indentation, and shows a function that creates a new 
paragraph (that should probably be hooked up to a key). Like all 
Lisp global variables, options must be declared "special" for the 
Lisp compiler (see "Compilation" below): 
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(declare (special paragraph-indentation)) ;for compiler. 

(register-option 'paragraph-indentation 10.) ; default is ten 

(defun new-paragraph {) 

(new-line) ?two new-lines 

(new-line) 

(whitespace-to-hpos paragraph-indentation)) ;tab out 



By issuing the request:/ 

ESC X. opt paragraph-indentation 5 CR 

You can set the amount of indentation inserted by new-paragraph 
to 5. 



NAME SCOPE ISSUES 

All of the functions and variables in the Lisp environment 
are accessible to all functions running in it. At times, this 
can be a problem. When adding your own extensions to the editor 
environment, nothing prevents you. from choosing a name for one of 
your functions that happens to be the name of some internal (or 
user-visible) function in Emacs. Occasionally, there may be 
reason to do this deliberately, e.g., writing your own version of 
next-line to do something special. This is dangerous, and not 
recommended. 



In general, you want to make sure that none of your 
functions or variables conflict with those of the editor. The 
best way to do this is to choose some set of names that minimizes 
the possiblity of conflict. To achieve this, use capital letters 
anywhere (such as initial capitals) or use underscores in your 
names, since almost no Emacs or Lisp system functions have 
leading capitals or trailing underscores. Watch out for the few 
exceptions: error_table_, e_cline_, Rtyo, Rprinc, ItoC, Ctol , 
and the DCTL functions for" writing terminal control modules. 
There are a few Lisp system functions with embedded underscores, 
but other than make^atom, it does not hurt if you accidentally 
redefine them. The Lisp compiler also warns you if you attempt 
to redefine a system function. No functions in Emacs contain 
underscores in their names. 



Another technique is to use double hyphens in your names. 
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Another way to avoid name scope conflicts is to prefix all 
of your names in a given package with some prefix indicative of 
the facility that you are trying to implement. For instance, if 
you are implementing a SNOBOL edit mode, you might name your 
functions "snobol-f ind-match-string" , "snobol-get-branch-target" , 
etc. The same holds true for global variable names. This is the 
standard, recommended, and most mnemonic way. 



You can also be reasonably certain that names constructed 
somewhat whimsically (e.g. , "Johns-special-tsplp-hack" , 

"f ind-third-f 00" , etc.) will not conflict. 



MODES 

The major and minor mode mechanism of Bmacs is a way for the 
user to switch in and out of large sets of key-bindings and 
column settings, and to be informed of this via the mode line. 



Major Modes 

A major mode involves a large body of optional code (e.g., 
PL/I mode), sets up for editing code written in a particular 
language, or sets up buffer for some highly specialized task 
where very common keys (e.g., CR) do nonobvious things (e.g., the 
Message mode buffers of the Emacs message facility). Minor modes 
generally involve the way that whitespace or delimiters are 
interpreted, e.g., fill mode and speedtype mode. 



Although modes can be invoked by explicit user commands, 
e.g., ESC X lisp-mode, modes are usually invoked via find-file 
(A^Ap) when a user reads in or creates a program and has elected 
the find-file-set-modes option in his start_up. When you invoke 
find-file with a suffixed file (and with find-file-set-modes 
elected), a check is made to see if a function named XXX-mode 
(where XXX is the suffix) has been defined. If such a function 
has been defined, it is invoked. If not, a check is made to see 
if the symbol XXX has a suffix-mode property? if so, the value of 
this property is a symbol denoting a function to be invoked. 
Thus, a form such as: 

(putprop 'ec ' exec-com-mode * suffix-mode) 

in a start_up causes all ".ec" segments to invoke the 
(hypothetical) function exec-com-mode. The defprop special form 
can be used to eliminate the quotes; thus, 

(defprop ec exec-com-mode suffix-mode) 

has the same effect as the form above. 
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A ma 
"XXX-mode" 
function" 
columns { 
necessary, 
per-buf f er 
indicates 
line: when 
following 
programs: 



jor mode is set up by a user-vis 
, where 2XX is the name of the 
establishes key-bindings (using 
e.g., fill-column, comment-column 
The mode function establishes the 
-variable "current-buffer-mode" to 
the mode. The name of the symbol 
the redisplay is invoked while i 
function sets up a major mode 



ible function called 
mode. This "mode 
set-key), and sets 

) and prefixes as 
mode by setting the 
a symbol whose name 
appears in the mode 

n this buffer. The 

for editing FORTRAN 



(defun fortran-mode () ;the mode function 
(setq: current- buffer-mode 'FORTRAN) 

(setg fill-column 70.) 
(setq fill-prefix" ") 
(set-key 'CR * f ortran-new-line) 
(setq comment-column 0) 
(setq comment-prefix "C ") 
( if f ortran-mode-hook 

( f uncall f ortran-mode-hook ) ) ) 

The function fortran-new-line is assumed to be one that does 
something appropriate, such as numbering cards. The use of the 
function set-key implies that this key binding (of the carriage 
return key) is local to this buffer, and will be reverted when 
this buffer is exited. 



; symbol 
;for mode 
;set columns 
;six spaces on CR 
;set up CR key 

;that begins cmts 



The above code checks the variable f ortran-mode-hook to see 
if it is other than nil and invokes the symbol to which it is 
bound if it is indeed not nil. 



The Lisp primitive f uncall is used to call functions that 
are the bindings of variables. It is like calling an entry 
variable in PL/I. The f uncall function accepts any number of 
arguments; its first argument is the function you wish to call, 
and its second-through-last (optional) arguments are the 
arguments that are to be supplied to the function being called. 
Consider the statement: 

(setq Z (f uncall X 1 2 4)) 

Suppose X is bound to the symbol +. The effect of evaluating the 
above statement would be to apply + to 1, 2, and 4, thereby 
assigning a value of 7 to Z. However, were X bound to * 
(multiply), a value of 1*2*4 (i.e., 8) would be assigned to Z. 
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The above code in fortran-mode assumes that 
fort ran -mode-hook will be bound to nil if it has not been set by 
the user. Of course, defvar elegantly provides for this. A 
statement such as: 

(defvar f ortran-mode-hook nil) 

should appear somewhere in the source of fortran-mode. 



Calling the mode-hook-function should be the last thing done 
by the mode function. 



Minor Modes 

Minor modes are less straightforward. Minor modes such as 
speedtype and fill mode have different actions associated with 
the keys they affect (for instance, all the punctuation keys), 
and the minor modes have to have detailed and specialized 
interaction between themselves. There is no way to generalize 
the interactions between the minor modes; no completely adequate 
solution to this problem has been developed. 



Minor modes are asserted and turned off in a given buffer by 
calling the functions "assert-minor-mode" and "negate-minor-mode" 
while in that buffer, with an interned symbol that identifies the 
mode (and appears in the mode line). A per-buffer variable 
called buffer-minor-modes has as a value a Lisp list of all the 
symbols identifying the minor modes in effect in this buffer. 
The Lisp predicate memq can be used to test whether a given 
interned symbol is a member of a list, and thus, whether a given 
minor mode is in effect in the current buffer: 

(memq 'fill buffer-minor-modes) 

returns a truth indication if fill mode is in effect in this 
buffer; otherwise, it returns "nil" (false). Functions 
implementing the actions of keys in minor modes should check in 
this way to see what other minor modes are in effect, and what 
they ought do in that case. 



The global variable fill-mode-delimiters is bound to a Lisp 
list of keys that act as punctuation in many minor modes. By use 
of the Lisp function mapc, all punctuation can be set to trigger 
a given action. The mapc function takes two arguments, a 
function and a Lisp list; the function is called upon each 
element of the list: 
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(defun no-punc-mode-word-on-a-line-mode-on () ;mode function 
(mapc ' word-on-a-line-setter fill-mode-delimiters) ;set 

; keys 

(assert-minor-mode ' word-on-a-line) ) ;get in mode line 

(defun word-on-a-line-setter (key) ;key is the key 

(set-key key ' word-on-a-line-responder ) ) ;set these keys 

(defun word-on-a-line-responder () ;key function 

(delete-white-sides) ;get rid of whitespace 
(self -insert) ; Insert the typed character 
(new-line) ) ? start a. new line. 

This set of functions establishes a minor mode in which each word 
goes on a separate line as it is typed. 

CHARACTER DISPATCHING' 

Several special forms and functions facilitate the making of 
decisions based upon the identity of the character to the right 
(or left) of the current point. All of these functions and forms 
accept either of two ways of describing characters: either a 
single-character string (e.g., "."), or a symbol whose name is 
that character (e.g., 'a, as it would appear in a program). The 
first kind, is called the "string form", and the second kind, 
"character objects". 



The function curchar, of no arguments, returns the character 
to the right of the current point as a character object (this is 
done for storage efficiency; character objects are unique, while 
strings require allocation). You can test for two character 
objects being the same unique object (or any two objects, in 
general) via the Lisp predicate eq: 

(if (eq (curchar) 'a) 

(display-error "You are looking at an ""a"".")) 

You could do this with the looking-at predicate described 
earlier, but for single characters, looking-at is a lot less 
efficient, in both time and storage. 



You cannot use eq to test if two strings have the same 
characters in them; Lisp strings are not uniquely defined in the 
same way that symbols are uniquely defined via the obarray. Use 
samepnamep instead. 
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In order to facilitate the use of special characters (tabs, 

linefeeds, spaces, quotes, etc.) in this way, several global 

variables have values of the character objects for these 
characters : 



ESC ASCII ESC, Ascii 033. 

CRET ASCII carriage return (Ascii 015) 

NL ASCII newline (linefeed), Ascii 012. 

SPACE ASCII blank, Ascii 040, 

TAB ASCII tab, Ascii Oil. 

BACKSPACE ASCII backspace, Ascii 010. 

DOUBLEQUOTE Ascii 042. 

SLASH /, Ascii 057, hard to type in Lisp code. 



A (eq (curchar) NL) is equivalent to (eolp). 



A special form to test if the current (to the right of 
point) character is a given character is called if-at ; 

(if-at "fit" (display-error "You can't have an ampersand here!")) 

Its syntax is the same as ^f, i.e., ^t has one, none, or many 
"then" and/or , "else" clauses, separated by the keyword "else" if 
there are any else clauses. However, instead of a predicate, 
if-at takes either a single-character string or a character 
object to be compared to the current character. If the current 
character is that character, the then forms are evaluated, etc. 
The if-at converts the character string to a character object at 
Lisp compile time, if necessary. The specification of the 
character must be a form that evaluates to the character of 
interest (e.g., "a", 'a, variable-bound-to-an-a) : 

(if-at TAB (delete-char ) 

(whitespace-to-hpos next-field)) ;tab to next field. 

The exact effect (and actual implementation) of if-at is as 
though it were shorthand for: 

(if (eq (curchar) ....) ) 



Similarly, a function called lef thand-char is like curchar 
except that it returns the character to the left of the current 
point; if the current point is at the beginning of the buffer, it 
returns a character object for a newline (which is almost always 
what you want). Similarly, an if-back-at special form exists, 
whose syntax and semantics are identical to if-at, except that it 
deals with the character to the left of the current point. 
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Two special forms for dispatching on the current (lefthand 
or righthand) character are called dispatch-on-current-char and 
dispatch-on-lef thand-char they dispatch upon the character to the 
right and the left of the current point, respectively: 

(declare (special parentable)) ;global variable 
(setq parentable nil) ?done when code is 

; loaded into editor 

(defun count-parens-in-buf f er () 

(if (not parentable) ; if not initialized 

(setq parentable (charscan-table "()"))) ;init it 
{let: ((leftcount 0) (rightcount 0)) ;init the counts 
( save-excursion ;be nice 

(go-to-beginning-of -buffer) 
(do-forever 

(if (not (search-charset-f orward parentable)) 

;loolc for ( or ) 
(stop-doing)) ;exit the do 
(dispatch-on-current-char ;see which 
( "(" (setq leftcount (+ 1 leftcount))) 
( ")" (setq rightcount (+ 1 rightcount)))))) 
(minibuf f er-print (decimal-rep leftcount) " opens, " 

(decimal-rep rightcount) 
"closes.") ) ) 

The general syntax of dispatch-on-current-char and 
dispatch-on-lef thand-char is as follows: 



(dispatch-on-current-char 

(CHI . <CHl-forml> 

<CHl-form2> 



<CHl-formn>) 
(CH2 <CH2-forml> 

<CH2-form2> 



<CH2-formn2>) 



(CHk <CHk-forml> 

<CHk-form2> 



<CHk-formnk>) 
(else <else-forml> 

<else-f orm2> 



<else-f ormn> ) ) 
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CHi can be any form that evaluates to a single-character 
string or to a character object. When the current character 
(left or right as appropriate) matches a CHi, all of the 
<CHi-form> in that clause are evaluated sequentially, and the 
value of the last returned as the value of the 
dispatch-on-current-char (nil is returned if there are no 
<CHi=form>). If no CHi matches, the else clause is evaluated as 
though it were a matching clause. The else clause is optional; 
if omitted, and no CHi matches, nil is returned. 



READING CHARACTERS FROM THE TERMINAL 

Some Emacs subsystems, such as query-replace, "read" 
characters from the terminal, without echoing them, and base 
their course of action upon the character read. This is not the 
usual method of causing characters to produce effects? the 
key-binding mechanism (i.e., set-key) is the usual way of causing 
requests to be invoked by the typing of characters. However, the 
extension writer may encounter a situation where he expects a 
single character response to some question, and this facility is 
provided. Use this facility carefully: the correct way to 
implement functions like the directory and buffer editors is via 
modes and key bindings, not loops that read characters from the 
keyboard. Similarly, the minibuffer query functions (e.g., 
minibuf -response and yesp) should be used to ask questions. 



The get-char function is provided to read the next input 
character; get-char returns the numeric value of the ASCII 
representation of the character. Bear in mind that the next 
input character may well have already been typed, since input to 
Emacs is treated as a stream of typed characters. Therefore, 
get-char does not return to its caller until a character is 
available. The get-char function also performs the necessary 
services of maintaining the input traces displayed by help-on-tap 
(^_L), . of handling keyboard macros, and of sampling for Emacs 
interrupts, such as those used by the Emacs console message 
system. 



The following Lisp functions, of one argument each, are 
provided to convert between numbers representing ASCII values of 



characters, single-character 
(single-character symbols): 



strings, and "character objects 



Function 
ascii 
ItoC 
Ctol 



Input 

number 

number 

single-character 
string or character 
object 



Output 

single-character object 
single-character string 
number 
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Occasionally, programs that read characters from the 
terminal are designed to allow normal Emacs requests to be 
processed during these operations. This usually takes the form 
of either an "escape character," which means that the next 
character (s) are to be interpreted as a normal Emacs request, or, 
alternatively, the interpretation, of all characters "not known" 
to the. program as Emacs requests (the former method is preferred 
since it is much cleaner) . 



The process-char function receives as an argument a number 
representing the ASCII value- of a single character to be 
interpreted as the first character of an Emacs request , and so 
interprets and executes it (including reading of another 
character if necessary) according to the key bindings in the 
current buffer. 



In principle, the basic loop of Em^cs can be expressed as: 

(do-forever 

(process-char (get-char)) 
(redisplay)) 

This is oversimplified; issues involving keyboard macros add some 
complexity, and the calling of redisplay is suppressed if input 
characters are available. Otherwise, the above code fragment is 
a correct description of the basic action of Emacs. 



PROGRAM DEVELOPMENT 

The editor itself provides many powerful tools for 
developing extension code and testing it while editing it. The 
following is a typical scenario in the development of an 
extension. 



You decide to write an extension. You sit down and think 
about it, and decide to code it. You enter Emacs. You do a ^X^F 
on the shaver. lisp file to go into a new buffer with a proper 
file name and select Lisp major mode (assuming that you have the 
option for find-file-set-modes "on"). Then type the form: 

(%include e-macros) 

at the top of your file; this is necessary to compile it (see 
"Compilation" below), or to use the ESC X loadfile request, 

i^Ae/-> T* T V-i<a*^ T-io 1 /^ti7 Tha f i 1 o o— mar" rnc in^l ^ ^ CTi chrMilH in t-ho 

— — — Ni.". ...W >, . ^ W . . . .-.--J^ 

"translator" search rules for your process. For efficiency, put 
a link to it in the directory in which you do Emacs extension 
development. Now begin to type in a function: 
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(%include e-macros) 

(defun shave-line () 

(go-to-beginning-of-line) 

At this point, to type the next line, lining it up with the last 
Lisp form, use the indent-to-lisp request, which is on ESC CR in 
Lisp mode, and the next form automatically indents properly; 

(delete-white-space) ; wrong name given deliberately here 

When typing in Lisp in general, ESC CR (in Lisp mode) indents you 
on the next line the right amount. So, continue with: 

(go-to-end-of-line) 
(delete-white-space) 



Now you are looking at the buffer with the code for 

"shave-line". To try it, load the code in the buffer into the 

editor. ESC in Lisp mode does this. Immediately, you get the 
message: 

Unbalanced parentheses. 

This means that there were not enough close parentheses 
somewhere: Emacs could not find the boundaries of the Lisp form. 
Fix the program problem. You are on the last line, so just type 
the close parenthesis: 

(delete-white-space)) 

Now do the ESC ^2 again. The- cursor returns to the function you 
are trying to edit. To see if it works, invoke it from Lisp: 

ESC ESC shave-line CR 

ESC ESC puts parentheses around what you type, evaluates it, and 
types out the Lisp value so returned. However, you find the 
message: 

lisp: undefined function: delete-white-space 

printed in the minibuffer, with the terminal bell rung, so you 
must have the wrong function name. Since you know it is on a 
key, type: 

ESC X apropos white CR 
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and learn about delete-white-sides. Now go to the first line 
that has the bad function name, do an @ to clear the line, ESC 
to line up to retype the form, and: 

(delete-white-sides) 
Fix the other bad Line, too, and again type: 

ESC ESC shave-line CR 
Surprisingly, it still says: 

lisp: undefined function: delete-white-space 

as though you had not changed anything. Indeed, fixing it in the 
buffer is not good enough. You must reload it into the editor 
environment; use ESC again. Now try it again: 

ESC ESC shave-line CR 

and immediately your function on the screen changes appearance; 
all the whitespace on the ends of the last line of the function 
disappears. It works, but its appearance is messy. This is a 
problem with editing what you are testing: it must either be 
innocuous, i.e., do something harmless, or you must be prepared 
to reconstruct damage your function does, or switch to a test 
buffer before running it. 



Fix your function, and you are almost done. Although it 
exists in an editor buffer, and in the editor Lisp environment, 
you must remember to write it out: 

-^X^S 

writes it out to shaver. lisp as you set up for initially. Now 

you have an operative Lisp program that you can use again. If, 
in a future invocation of the editor, you need to use it, you 
type: 

ESC X loadfile <path>shaver . lisp CR 

and get it into the environment. There are two problems with 
this, however: 

1. Whoever loadfiles must have e-macros . incl . lisp in his 
translator search rules. 

2. The code is executed interpret ively by the Lisp 
interpreter in the Lisp subsystem; Emacs is compiled 
Lisp, and compiled Lisp runs up to 100 times faster 
than interpreted Lisp and has fewer problems. 
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Thus, the file shaver. lisp should be compiled. Then, the 
compiled object segment can be loaded into the editor with: 

ESC X loadfile <path>shaver 

See below for a description of how to compile Lisp programs. 



Coding Problems 

Some other problems are of immediate interest to the 
extension writer. It is possible, and fairly common, to write 
loops that do not terminate, or that generate infinite garbage. 
If you invoke your request, and the cursor never leaves the 
minibuffer, and seems to have no effect, you are in a loop. 
Hit QUIT, and use the program_interrupt (pi) Multics command to 
reenter Emacs. If you are singularly unfortunate, you get: 

lisp: (nointerrupt t) mode, unable to accept interrupt 

in which case you are stuck in the process of generating infinite 
garbage. In this case, you must release, and your editing 
session is lost. If you are more fortunate, you will get your 
screen back, with the cursor at the place your function left it. 
Often, by looking at exactly where it left it, you can get a good 
idea of what kind of thing was giving your program a hard time. 



If you get messages from Multics that tend to indicate that 
there is no more room in your process directory, you are probably 
generating an infinite number of lines, i.e., an infinite buffer. 



Another thing that can happen is you might expose some bug, 
or what you believe to be a bug, in Emacs, or worse yet, Multics 
Lisp. Use the trouble report forwarding mechanism to describe 
what you encountered and why you think it is a bug. 



You can also destroy the editor environment by bad coding. 
This is particularly true in running compiled code that was not 
checked out interpretively ( i .e. , via ESC ^Z). Storing into 
"nil" is one common way to do this. If the entire editor seems 
broken, and the redisplay does not even show the screen, this is 
what you have done. Quit and release and start all over again. 



A function called debug-e is called as: 
ESC X debug-e CR 
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It sets "(*rset t)" mode and other Lisp debugging aids, and 
unsnaps all "lisp links". It also reverts to native Maclisp 
QUIT/pi handling. To use this, however, you" must be familiar 
with the debugging features of Multics Maclisp. 



To get the value of. a global variable to be printed out, 
say, fill-column, type: 

ESC ESC progn fill-column CR 

Be careful,, for values typed out are in octal.. 



A Lisp code debugging facility within Emacs, called LDEBUG, 
or Lisp Debug mode, allows for the setting of breakpoints, 
dialogue with Lisp within Emacs, tracing, and so forth. See 
Section 4. 



COMPILATION 

All production Multics Lisp programs are compiled. This 
results in a tremendous performance improvement, both for the 
user and the system. Compiled Lisp programs are executed 
directly by the Multics processor; interpreted programs are 
interpreted by the Lisp interpreter. Emacs is compiled Lisp. 



The Lisp compiler is a Multics program that can be invoked 
from command level. It has the names Icp and lisp_compiler . To 
compile a program named my funs. lisp, you say: 

Icp myfuns 

to Multics, and you get an object program named "myfuns", which 
can be loadfiled, in the working directory. 



The compiler diagnoses Lisp syntax errors. It warns you of 
implied special variables (if you did not declare a variable 
special, and it is not a local variable in the function in which 
it was referenced, you probably made a mistake. All global 
variables should be declared for this reason? e-macros declares 
the provided ones.) 



At the end of compilation, the compiler prints out the names 
of functions referenced in the code but not defined in the file. 
This is normal; however, you should inspect the list it prints 
out to see if any are ones that you thought you defined; if so, 
you have a problem. Check also for ones that are obvious typing 
errors . 
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While editing a large extension program, you may wish to 
load only the function that you are looking at on the screen into 
the editor environment. The function compile-f unction , on ESC '^C 
in Lisp mode, compiles the function you are looking at (whose 
start is found by ESC '^A from where you are now) into a temporary 
segment in the process directory. It then loads the object 
segment, and displays the compiler diagnostics via local 
printout. It should be used with the cautions noted below. When 
using it, remember to write out your changes, and recompile your 
whole program, because a program incrementally debugged in this 
mode gives the impression that it is working properly when it is 
only doing so in the current editor environment. 



Compiling functions via ESC '^C is often advantageous; the 
compiler produces diagnostics that help locate errors that you 
might not have encountered until your function ran, or perhaps 
not even then. ESC '^C effects compilation and loading of the 
current Lisp function into your Emacs environment by loading the 
Lisp programs that constitute the Multics Lisp Compiler into your 
Emacs environment and invoking them. The loading happens only 
the first time Lisp mode ESC ^C is used in an invocation of 
Emacs, and Emacs tells you when it is doing this. Emacs also 
loads the correct version of the e-macros include file during 
this first invocation. 



Forms compiled by Lisp mode ESC ^C are treated as though 
they had been encountered by themselves in a source file being 
processed by the Lisp compiler. As viewed by the Emacs user, 
successive compilations of functions via ESC ^C appear to be 
successive invocations of the Lisp compiler. This, however, is 
not an accurate description of what is taking place. As viewed 
by the Lisp compiler, which is then "living" in the Emacs 
environment, it is compiling one large source program consisting 
of many functions (i.e., successive uses of ESC ^C); all editing 
activity "between ESC '^Cs" is irrelevant to it. Thus, invoking 
ESC ^C for a Lisp macro definition defines that macro for all 
functions compiled by ESC '^C in that invocation of Emacs from 
that point on. Therefore, you must ESC '^C Lisp macro definitions 
if you intend to compile or evaluate function definitions using 
these macros. (In the case of macro definitions , ESC ^C 
(compilation) is equivalent to to ESC ( evaluation ) . Macro 
definitions,- whether ESC ^Ced or ESC '^Zed, are accessible to 
functions ESC '^Zed or ESC '^Ced. ) 
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similarly, Lisp "reader macro" character definitions must be 
evaluated if they are to be utilized by ESC '^C, Declarations of 
special variables (other than those declared for you in 
e-macros . incl, lisp) should also be ESC '^Ced (not ESC ^Zed) if 
they are to be respected by functions being ESC '^Ced. Often, if 
you. fail to do this, the compiler (ESC '^C) automatically detects 
undeclared use of special variables and warns you; however, in 
certain cases (most notably binding them via let), it does not , 
and erroneous code results. 



The compiler accumulates compilation diagnostics in the 
buffer named ^Compiler Diagnostics." Diagnostics for each 
application of ESC '^C are- displayed as local display. 



DOCUMENTING REQUESTS 

The automatic documentation system (apropos, ESC ?) 
provides customized Emacs request documentation. Documentation 
for supplied requests is kept in a special file in the Emacs 
environment directory.. You can provide documentation for your 
own requests by placing a string, which is that documentation, as 
the "documentation" property of the symbol that is the request 
being documented. For instance, if the symbol 
remove-every-other-word has the documentation property of: 

"Removes every other word from the sentence in which the 
cursor appears." 

this information is displayed by ESC ? when used on some key set 
to remove-every-other-word, or by: 

ESC X describe remove-every-other-word CR 



Documentation properties are assigned most conveniently via 
the Lisp- special form "defprop", whose general syntax is: 

(defprop SYMBOL WHAT PROPERTY) 

This assigns the symbol (SYMBOL) a property (PROPERTY) of WHAT. 
The defprop is a special form because the actual symbols 
appearing in the form are used; they are not variables, as in "(+ 
a b c ) " . Thus , 

(defprop Joe Fred father) 
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gives the symbol "Joe" a "father" property of "Fred". (The 
"defprbp" is a special-form way of doing the same thing as the 
"putprop" function, but it is a special form because its 
"arguments" are not forms to be evaluated to produce symbols 
whose properties are to be dealt with, but the symbols 
themselves). To use defprop to establish Emacs request 
documentation, place forms like; 

(defprop remove-every-other-word 

"Removes every other word from the current sentence. Will 
not work on sentences ending in ""7""^ por indented 
sentences, use $$remove-other-word-f rom-indented-sentences$ . 
$$$ is a powerful, dangerous, command." 

documentation) 

Note several things about the documentation string: 

1. It does not need to end in a newline, and can contain 
newlines. 

2. Quotes (") inside of it must be doubled. 

3. The string "$$$" will ' be replaced by the key being 
asked about (e.g., "ESC ^Z" or "ESC X 
remove-every-other-word") at the time the documentation 
is displayed. 

4. The keys used to invoke other requests can be 
referenced by stating two dollar signs, the name of the 
request, and one dollar sign. Thus, 
$$go-to-end-of-line$ appears as in most 
environments; the point of this and the previous 
paragraph is to make documentation expansion 
independent of a user's key-bindings. 

The entire documentation string is "filled" (ESC Q) after 
all command-name substitutions are made; thus, the placement of 
newlines in the documentation string is ignored. Two consecutive 
newlines, however, are preserved, and thus, lines can be set off 
for examples, etc., by surrounding them with blank lines. 



It is slightly more efficient, but clearly less readable, to 
place the defprop documenting a request before the defun defining 
the request itself. The defcom facility can also be used to 
document requests; see "Defining Requests With defcom" below. 
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WINDOW MANAGEMENT 



Although buffers appear in windows on request, and are 
switched between automatically by the redisplay when you switch 
windows with ^X^O, '^X4, etc., there are times when you may want 
to take advantage of multiple windows explicitly. Good examples 
in supplied code are RMAIL reply mode and the comout -command 
(^X'^E) ... 



Most of the extensions of interest, are ones in which the 
extension writer wants to place some information in a buffer, or 
else prepare some buffer to have information placed in it (e.g., 
RMAIEl reply) and then display that information in a window. 
Usually, all that is required is to "go to" that buffer (e.g., 
with go-to-buffer or go-to-or-create-buf fer ) . The redisplay 
"finds'^ the editor in that buffer at the time of the next 
redisplay, and replaces the contents of the selected window on 
the screen. Such requests are called autophanic (self-showing). 
Examples are '^XB (select-buffer) and ^X'^F (find-file). 



However, some requests set up buffers in some window other 
than the current window, usually for multi-window operations such 
as mail reply, so as not to disturb the contents of the current 
window. They are called heterophanic (other-showing). The 
standard examples are dired-examine , mail reply, and 
comout-command ('^X'^E). All the examples given are sub-requests 
of larger, autophanic requests. 



Heterophanic buffer behavior is provided by the function 
f ind-buf f er-in-window It takes as an argument a buffer-symbol 
(Lisp symbol representing a buffer). That buffer is created if 
it does not now exist, and is gone to, as if go-to-buffer had 
been used. If Emacs is in single-window mode, the effect is the 
same as that of go-to-or-create-buf f er . In two-window mode, that 
buffer is put on display as follows: 

B If it is already on display in some window, it is left 
there. 

B If it is not , it is put on display in some other 

window, one in which the cursor is not, and the cursor 

moves to that window, as if a '^X'^O had been done. The 
least-recently used window is chosen. 
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Thus, on printing terminals and in single-window mode, the 
effect of f ind-buf f er-in-window is indistinguishable from that of 
go-to-or-create-buf f er . In multi-window mode, it is equivalent 
to go-to-or-create-buf fer, displaying that buffer in another 
window. 



You must not use find-buff er-in-window to place a buffer on 
the screen once you have already gone to it? if you think of 
find-buff er-in-window as a kind of go-to-or-create-buf fer , you 
will find no need for doing so. 



An extension must establish multiple windows if it needs 
them; no current Emacs code requires multiple windows, although 
the facilities mentioned above are more useful when already in 
it. 



Most extensions that place an auxiliary buffer on display 
via find-buff er-in-window provide some request to return to the 
"main" buffer (e.g., the RMAIL Incoming Message buffer, the 
buffer from which ^X^E was issued, etc.). If you enter a buffer 
via find-buff er-in-window, you should probably return to the 
buffer from whence you came via find-buff er-in-window as well; 
the effect of this is to restore not only the original buffer, 
but also the original window. Thus, save-excursion-buf f er cannot 
be used effectively to return from buffers entered via 
find-buff er-in-window; an attempt to use save-excursion-buf fer 
results in both windows* showing the same buffer, since the 
selected window (i.e.., the cursor-bearing window) is changed and 
a new buffer selection means a new buffer in that window. 



The '^X^Q key sequence should be used to exit auxiliary 
buffers used by extensions to return to their main buffer, and 
usually switch windows as well, if the multiple-window strategy 
outlined above is used. 



Pop-up window mode, in essence, makes all requests 
heterophanic . Requests or subrequests that are naturally 
heterophanic need not worry about pop-up window mode, because 
find-buff er-in-window takes the appropriate action in either 
pop-up or non-pop-up mode. However, if proper heterophanic 
behavior under pop-up windows is desired, naturally autophanic 
requests and subrequests must call a window-management primitive 
to obtain heterophanic behavior in pop-up window mode. This 
primitive is called select-buffer-window. It takes two 
arguments, a buffer-symbol, and a "key" that, gives pop-up window 
management a preferred window size. 
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In non-pop-up window mode, select-buffer-window is 
equivalent to go-to-or-create-buf f er , and the key is ignored. In 
pop-up mode, it is equivalent to f ind-buf f er-in-window , with the 
key suggesting the new window size. 

The following values for the key argument to 
select-buffer-window are accepted. They specify the window size 
in pop-up mode if the window does not exist, already: 

any number 

That many lines- 

* cur size 

Make a choice based on the current number of lines in 
the buffer, 

nil 

Chooses some reasonable fraction of the screen. 

* cursize-not-empty 

Same as nil if the buffer is empty; same as 'cur size if 
it is not. For example, ^X'^F uses this, because you 
can type into a new buffer. 

* default-curs ize 

If this buffer has never been displayed before, makes a 
choice based on the number of lines. Otherwise, uses 
the same size was chosen last time. 



The find-buff er-in-window can not be used to display the 
"current buffer" heterorphanically . If you attempt to do this: 

( find-buff er-in-window current-buffer) 

you find it appearing in both the old and new windows, for the 
window manager finds that you were in this buffer in the current 
window (a truth) before you went to another one (you had to go to 
another one, as per heterophanic behavior), and indicates that 
the current buffer is to be displayed in the old window as well, 
for that was the last buffer you were in in that window. To 
avoid this, use select-buffer-find-window (of two arguments, the 
buffer and a key as for select-buffer-window) if heterophanic 
display of the current buffer is needed: 

(select-buffer-find-window current-buffer nil) 

This is rare, since you seldom go to a buffer and then want to 
f ind-buf f er-in-window it; in Emacs, only '^X^E does this. 



3-54 



CJ52-01 



since all things using these features are moderately 
sophisticated, only an outline of an extension using them is 
given here. It is a typical sub-subsystem (e.g., dired) that 
sets itself up in an autophanic buffer display, with specific key 
bindings, etc., and has a heterophanic subdisplay by which it 
displays a "menu" in addition to the main display: 

(defun unusual-mode () ;Setup function for this mode 



(go-to-or-create-buf f er (maknam 

(explodec "Unusual buffer"))) 
(set-key 'ESC-^S 'unusual-mode-show-menu) 
(select-buffer-window current-buffer nil) 
( register-local-var ' unusual-mode-buf f er-to-return-to) 
• . ) 



(declare (special unusual-mode-buf f er-to-return-to) ); for compiler 
(defun unusual-mode-show menu () 

(setg unusual-mode-buf f er-to-return-to current-buffer) 

;save buffer 

( find-buff er-in-window 'Unusual -Menu) jDisplay menu 
(set-key 'r ' unusual-mode- select- item) ;Set key bindings 
(set-key "^X^Q 'unusual-mode-menu-return) 
(insert-string "Unusual menu delicacies") ;Fill it up 
;; Will not actually be displayed until request finishes. 



(go-to-beginning-of -buffer) 

(setq current-buffer-mode 'Unusual/ Menu 

buf f er-modif ied-f lag nil read-only-flag t) 
^ 

(defun unusual-mode-menu-return () 

(find-buff er-in-window unusual-mode-buf f er-to-return-to) ) 
;;Return to calling buffer. 



The following are several primitives available to deal with 
windows by window number. The topmost window on the screen is 
window number 1; the next one down, if any, is number 2, etc., 
(the minibuffer and mode line do not count as windows). The 
selected window is the one in which the cursor currently appears. 

selected-window 

This variable contains the number of the currently 
selected window. Do not attempt to setq it to select" a 
window; use select-window instead. 

nuwindows 

This variable contains the number of windows on the 
screen; do not attempt to setq it to create or delete 
windows; use delete-window and the ^Z2 and 
functions to do these things. 
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select- window 

This function (of 
selects that window 

delete-window 

This function (of one argument, a window number) 
removes, that window from the screen, distributing its 
space to the other windows, 

buf f er-on-display-in-window. 

This predicate function (of one argument, a 
buffer- symbol) returns truth if the specified buffer is 
ort display in some window on the screen. If used as a 
function , i.e., the value returned is inspected, the 
returned value the window number in which the specified 
buffer is on display (if it is not on display, the 
symbol '*nil",. representing falsity, is returned). 

window-info 

This function (of one argument, a window number) 

returns information about that window. The information 

is: ia the form of a piece of Lisp list structure, which 

can be interpreted by the Lisp list destructuring 

window-info, the following forms return the information 
as follows: 

(caar info) => 

(cdar info) => 
(caddr info) => 

(cadddr info) => 



w indow-ad j us t- upper 

A function of two arguments, the first a window number, 
and the second a signed number of lines to move its 
upper divider-line down (negative is up). 

window-adjust-lower 

Same -as window-adjust-upper , but deals with lower 
divider line. 



one argument, a window number) 
(as ^X4 with an argument does). 



The top line-number on the screen of 
the window. The topmost is 0. 
The number of lines in the window. 
The buffer-symbol of the buffer on 
display in the window. 
A string duplicating the contents of 
the "cursor line" of the window, 
including its newline character. The 
cursor line of a buffer is that line 
where the cursor is (if it is in the 
selected window) or would be if that 
window became selected (e.g., with 
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WRITING SEARCHES 



Several functions aid in providing search-type requests. 
These functions prompt for the search string, provide default 
search strings, and announce search failure in a standardized 
way. All supplied Emacs searches use them* 

get-search- St ring 

Takes one argument, the prompt. The prompt should 
contain the word "search". The get-search-string 
prompts the user for a search string, which the user 
must terminate with a CR, and returns it as a string. 
If the user gives a null string, the last search string 
is used and echoed. The last search string is set to 
the returned string for the next defaulting. 

search- failure-annunciator 

Causes the "Search Fails." message to appear in the 
minibuffer, and a command-quit i^G) to be performed. 
This aborts any keyboard macro collection or execution 
in progress. 



When writing a search-type request, you should provide two 
interfaces, a "command", which calls the above two primitives, 
and a "search primitive", also called by the "command". The 
search primitive should return t (truth) if the search succeeds, 
leaving point at the proper place, as the search defines. If the 
search fails, the primitive must return nil (falsity), and leave 
point where it was when the primitive was invoked. 



A simple implementation of a wraparound search, below, first 
looks from point to the end of the buffer for the search string. 
If that fails, it goes to the top and searches again. It is not 
optimal because it needlessly scans farther than the original 
point when starting from the top. Using point>markp and 
searching a line at a time would be very expensive, due to 
point>markp* s expense. Searching a line at a time using 
forward-search-in-line and maric-on-current-line-p would be 
acceptable, but more complex than this example need be. For a 
search that is probably going to be used only as a user interface 
(i.e., not internally), this implementation is adequately 
efficient. Recall that with-mark releases its mark and returns 
it last value. 



3-57 



CJ52-01 



Here is the internal primitive for wraparound search: 

(defun wraparound-search-priaitive (string) 

(with-mark m ; Remember starting point 

(if (forward-search string) ?Look to end of buffer 
t ; Return truth 

else 

(go-to-beginning-of -buffer) 
{it (forward-search string) ?Looic from top 
t 

else 

(ga-to-marlt m}. ;Return to orig, place 
nil) ) > > ) ^Return falsity 

IP with-marit and this functioa 
r? return the value of the outer "if"^ 



The request for calling the primitive: 

(defun wraparound-search ( ) 

(if (not (wraparound-search-primitive 

(get-search-string "Wraparound Search: **))) 
(search- failure-annunciator) ) ) 



The wraparound-search request should have some key bound to 
it if this type of search is to be made available from the 
keyboard. 



CALLING. MULTICS COMMANDS 

la some extensions, especially those like DIRED that 
manipulate the Multics environment, you must call Multics 
commands, or execute Multics command lines. 



Multics command lines are strings submitted to cu_$cp for 
execution. This is the Multics agency to which the "e" requests 
of the Multics edm and qedx editors, the requests of 

readjnail, send_mail, and debug, and other subsystems submit 
command lines. The two primitives for executing Multics command 
lines are: 

e_cline_ 

Takes one argument, a string, which is passed to cu_$cp 
for execution. No reattachment of output takes place. 
If the command line produces output, it messes up the 
screen. This should only be used when no output is 
anticipated, and should be used then in preference to 
comout-get-output , since it is much faster. 
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comout-get-output 

Takes any number of arguments, which may be strings or 
symbols, and catenates them with one space between them 
to form a Multics command line, facilitating things 
like: 

(comout-get-output 'delete this-seg '-bf) 

Reattaches user_output and error_output during the 
execution, rerouting them to a process directory file. 
When the command execution completes, the contents of 
the current buffer are obliterated (!) and the 
temporary file read in to it. This is the primitive 
that comout -command ('^X'^E) uses; e_cline_ is used by 
comout-get-output internally. 

These primitives set up a condition handler that catches all 
abnormal Multics signals and aborts to a second Multics command 
level with a message if one occurs. However, requests for input 
by these command lines cannot at this time be dealt with well. 
In the case of e_cline_, the user gets the query in raw teletype 
modes, and has to answer it in raw, nonedited teletype modes. In 
the case of comout-get-output, the query never appears, having 
been routed to the temporary segment, and the user's process 
hangs since the user, having never seen the query, does not know 
to respond. 



MULTICS ERROR TABLE 

To get the value of standard Multics error codes, from 
error table_, into a program to see if a given Multics interface 
has Tn fact returned it, the function "error__table_" (with 
underscores, not hyphens) is used. Its single argument is a 
symbol, whose name is the name of the error_table_ entry whose 
value is sought, and the returned result is that value, or 1 if 
it is not a valid entry. 



The error_table_ function optimizes finding the same name 
over and over again, so you need not go through machinations to 
save an error_table_ value computed by these means. An example 
of the use of error_table_ follows: 

(let ((status-result (hcs_$get_user_ef fmode dir entry ""))) 
(if (not (= (cadr status-result) 0) ;the return code 
(if (= (cadr status-result) 

(error_table_ ' incorrect_access) ) 
(display-error-noabort "Warning: not checking 
access") 

else 

(display-com-error (cadr status-result) dir 
entry)))) 
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I EMACS ERROR SYSTEM 



Emacs has its own error system, with several functions 
available. They provide more error information than do the 
display-error and display-error-noabort functions (which simply 
take a string argument), because they are tied into the Emacs 
Error Table. 

report-error 

aborts: the current computation and prints an error, 
report-error-noaboct 

prints anr error without aborting.. 
add-e r r o r-code 

adds an entry to the Emacs Error Table 
error-table 

gets a standard Multics error code and returns the 
numeric value.. 



I Their syntax is: 

I (report-error error-code error-information) 

I (report-error-noabort error-code error-information) 

I (add-error-code error-code error-string) 

I (error-table segment offset) 



I where: 

I error-code 

I is a symbol representing an entry in the Emacs Error 

I Table (e.g., ' beginning-of-buf f er ) , or is a standard 

I Multics error code, or is a symbolic Multics error 

I code, e.g., error_table_$moderr . 

I error-information 

I is any number of objects to print in the error report. 

I error-string 

I is a string describing the error. 

I segment 

I is a Multics error table segment. 

I offset 

I is the symbolic name of an error table entry, e.g., 

I "m.oderr" in error table $moderr- 
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Defining Requests With defcom 

The defcom (for de f i ne ^ command ) facility simplifies the 
definition of Lisp functions to be used as Emacs requests, 
Defcom cooperates with the Emacs command reader to provide 
prompting and defaulting of unspecified arguments, range-checking 
of numeric arguments, automatic repetition for numeric arguments, 
cross-connecting symmetrical functions via negative arguments, 
and other features. 



Defcom is a relatively new facility in the Emacs extension 
environment; not all of Emacs* internal code has been converted 
to use it* Perusing the Emacs source, you will find examples of 
defcom* s use intermixed with older examples using defun to define 
request functions. 

■ Defcom should only be used for defining functions actually 
to be used as Emacs requests; internal and auxiliary functions to 
be used- by these functions should still be defined with defun. 
Emacs requests defined with defun will work, but those defined 
with defcom produce better diagnostics and offer more features. 
Defcom is a technique whereby the necessary defuns are generated 
automatically, so functions defined with defcom can be called 
from other functions, as well.. 

To define a function with defcom^ use defcom instead of 
defun, and supply no Lisp argument list: 

(defcom one-word-f rom-beginning 

(go-to-beginning-of -buffer) 
(forward-word)) 

This is the simplest form of defcom; optional features are 
supplied by placing, between the function name and the function 
code, various keywords, all of which begin with the 
character, and some of which take optional arguments, expressed 
as lists. 

The most common optional specification is &numeric-argum.ent , 
(or &na), which specifies what to do with a supplied numeric 
argument. The keyword tnumeric-argument must be followed by a 
list of specifications, which must include one of the following 
major processing types: 

Sireject 

Any numeric argument is rejected as invalid. No other 
specifications are valid in this case. This is the 
default if &numeric-argument is not given. 
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^ignore 

A. numeric argument is ignored, 
^repeat 

If the argument is positive, the request is repeated 
that many times. 

&pass 

The value of the Lisp variable "numarg" is set, as in 
nondefcom requests 



la addition to the major processing type, optional bounds 
can be specified by the keywords &upper-bound (&ub) or 
&lower-bound. (Silb).. These, in turn, must be followed by either 
an integer representing the bound, or the keyword Seval followed 
by an expression to evaluate at the time command execution is 
attempted, which then produces a value (such an expression is 
called an "Steval expression".) Here are some examples of 
Scnumeric-argument specifications: 

Staumeric-argument (&pass) 

£ n-ume r i c - sr r g urns n t 

^fcrepeat Slower -bound 1 

fitupper-bound fieval (+ max-foos 2)) 

&numer i c- a r gumen t 

(Stpass Stupper-bound 15.) 



Another optional function which specif ies what 'to do with a 
supplied numeric argument is &numeric-f unction. The 
&numer ic-function function doesn't actually do anything with the 
supplied argument. Instead, it causes a different request to be 
executed if the original request is given a numeric argument. 



j Here is an example of a &numeric-f unction function 

I definitionr 

I {defcom- global-print 

I &numeric- function global-regexp-print 

I . •■ )' 

I It can be invoked as: 

I in which case the global-regexp-print request is executed instead 

I of the' global-print request. 



2/83 



3-62 



CJ52-01A 



A request defined with defcom may elect to receive Lisp 
arguments, values that are to be prompted for or supplied as 
extended request arguments. They can be provided automatically, 
and prompted for, by the Emacs command reader, and supplied as 
Lisp arguments to the request function. Instead of a normal Lisp 
argument list, the keyword ^arguments (or &args or ta) are 
followed by a list of argument specifications, one for each Lisp 
argument to be supplied. 



Each argument specification consists of the Lisp name of the 
argument, i.e., the name of the variable to be referred to inside 
the function, and any number of argument qualifiers, separated by 
spaces. Each argument qualifier can consist of several tokens, 
as necessary. Argument qualifiers specify the prompts, defaults, 
etc., for an argument. An argument specification may also be 
given as the name of the variable alone, as opposed to a list of 
it and qualifiers. In this case, it is equivalent to having its 
own name as a prompt for its value. 



When a def corn-defined request is invoked as an extended 
request, (i.e., via ESC X), the Emacs command reader checks the 
type and number of request arguments supplied and necessary, and 
prompts for those not supplied, or defaults them as specified. 

When a defcom-def ined request that has arguments is invoked from 
a key, it is as if it were invoked as an extended request with no 
request arguments given, and all are either prompted for or 
defaulted. 



The valid argiament qualifiers are.: 

StString 
& symbol 
^integer 

Specifies how the argument, when read by ESC X or 
prompted for, is to be converted before being passed. 
Only one of these is valid in a given argument 
specification, and StString (i.e., no conversion) is the 
default. 

ttdefault 

Must be followed by either a string, symbol, or 
integer, as consistent with the expected data type for 
this argument, or an &eval expression. Specifies the 
default value to be used if this argument is not 
supplied, or a null response is given to a prompt for 
this argument, if any. 
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Suprompt 

Specifies the prompt for this argument, if not supplied 
via ESC X. Prompts are put to the user before defaults 
are evaluated or used; a null string causes the 
&de fault value to be used. An Stprompt is followed by a 
prompt, string (in quotes), or an Sceval expression, and 
one of the two optional keywords NL. or ESC, specifiying 
the- prompt terminator (NL is the default), 

S rest-a s- 1 i s t 

Valid only foe- the last: argum'^nt. Causes this variable- 
tor be given", as a value, a liist: of ail of the remaining 
STapplied arguments. If £rest-a.s-list is used, the 
caller of this function from Lisp (including start-ups 
writteh by not-Lisp-conscious users) must know that the 
number and organization of Lisp argiiments is different 
from the. apparent argument array given to ESC X. 

St re s t-a s - s t r i n g 

Valid only for the last argument; causes all remaining 
arguments to be supplied as a si-ngle string to the 
function, as they appeared to ESC X, with spaces and so 
forth included. Same cautions as for &rest-as~list 
applyv 



A function definition that accepts three arguments follows: 

(defcom replace-n~times 
Sarguments 

((oldstring &string &default Steval 

(get-search~string "Old: ")) 
(hewstring Sstring &prompt "New String: " NL) 
(count Siinteger Stprompt "How many times? " NL 

Stdefault 1) ) 

(do-times count 

(if (not (forward-search oldstring)) 

(search-failure-annunciator) ) 
(do-times ( str inglength oldstring) (rubout-xhar) ) 
(insert-string newstring))) 

It can be invoked as: 

ESC X replace-n-times Washington Lincoln 2 CR 



ESC X replace-n-times CR 
in which case all arguments are prompted for, or: 
set-perm-key ^ZS replace-n-times 
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followed by striking ^IS at some time, prompts for all arguments, 
too. This function is defined so that it can be called from Lisp 
as: 

(replace-n-times "this" "that" 17) 
or whatever, i.e., it is a Lisp function of three arguments. 



When def com-def ined requests are reexecuted by ^C, they are 
repeated with identical arguments. This is what makes 
search-repetition by '^C work. 



In addition to numeric arguments 
def com can be used to specify 
documentation, cleanup functions, and 
request functions.- 



Prologues are functions or code to be executed before any 
arguments are prompted for, perhaps to check for valid 
circumstances for calling this request. Prologues are only | 
executed once. If the request is repeated because of a numeric j 
argument, prologues are not repeated with each iteration, j 
Prologues are specified by the keyword Stprologue, and the name of 
a prologue function or an teval expression. 



and request arguments, 
prologues, epilogues, | 
negative functions of | 



Epilogues are functions or code to be executed after each { 

invocation of the request. If the request is repeated because of | 

a numeric argument, epilogues are repeated after each iteration. | 

Epilogues are specified by the keyword Stepilogue, and the name of j 

an epilogue function or an S^eval expression. The epilogue | 

function takes three arguments and is called as follows: | 

(function prologue-info result lastp) | 

where: j 

prologue-info | 

is the value returned by the prologue function, or nil if j 

there isn't one. | 

result I 

is the value returned by the request itself on this | 

iteration. j 

lastp I 

is non-nil if this is the last (or only) iteration. | 
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Documentation is specified by the keyword Stdocumentat ion (or 
Stdoc) followed by a documentation string subject to the same 
rules, as given above under "Documenting Requests". 



Cleanup functions are functions or code to be executed if 
the request is aborted.. Cleanup functions are specified by the 
keyword Scleanup, and the name of a cleanup function or an &eval 
expression. The cleanup function takes one argument and is 
called, as followsr 

(functiarr prologue-info) 

where : 

proiogue-inf o 

is the. value returned by the prologue function, or nil 
if there isn't one., 



Negative functions are functions or code to be executed if 

the request is given a negative numeric argument: the negative 
function is given the negative numeric argument made positive. 
Negative functions are specified by the keyword 
Scnegative-funct ion (&nf), followed, by the name of the appropriate 
function, or forms, terminated by &end-code. The following is an 
example of the use of some of these features: 

(defcom forward- topic 

Stdoc "Goes forward one or more topics. See also 

$$backward-topic$. " 
Stnumeric-argument (Srepeat) 
inegative^f unction backward- topic 
(with-mark m 

( forward-search "Topic : : " 



Emacs determines whether a character should stop echo 
negotiation by checking a list named "nobreak-f unctions" . The 
defcom keyword Scno-break adds the command being defined to the 
list. Keys bound to symbols on the list are echoed by the FNP, 
and do not interrupt the process (unless at end of line). 



Another defcom keyword, ^completions (or Stcompletion , &comp) 
provides minibuffer prompt completions. It allows any 
def com-def ined command to define completions that should be in 
effect for a given argument. The ESC SPACE request, 
complete-command, uses these completions to complete minibuffer 
input. An example of the Stcomplet ions keyword is below: 
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(defcom new-function 

Siarguments ((argl ^prompt "What is arg one? " 

Sccompletions '{"one" "two")) 
(buf Scprompt "OK, and in what buffer? " 
Sccompletions known-buf list ) ) 
(minibuf f er-print "Buffer is " buf ", argl " argl ".")) 

The argument after the ^completions keyword is evaluated at the 
runtime of the function. The current list of completions is kept 
in the lisp variable completion-list. 



UNDOING A REQUEST 

The undo-prefix command, sets the variable "undo" to t, 

which causes the next function called to attempt to do the 
reverse of its usual action. Def com-def ined requests make use of 
this through the Scundo-f unction (&undo, ^inverse) keyword. Its | 
syntax can take one of six forms: 

Stundo (&pass) [or the equivalent &undo &pass] 

Stundo (^ignore) [or the equivalent &undo &ignore] 

Scundo (Screject) [or the equivalent &undo Sreject] 

Scundo function-to-call 

Stundo (lisp expression to call) 

&undo &code lisp expressions &end-code 

If the defined request is prefixed by ^\ when called, then the 
special action is taken. Thus, if any of the last three forms is 
used, the function specified after the keyword is called instead 
of the def com-def ined request; if the first form is used, the 
variable "undo" is set to t and no special action is taken. This 
would mean, for example that "&undo &pass," used in the 
definition of re-execute-command i^C) , causes the sequence ^\^C 
to attempt to undo the last request executed. The second form 
causes the undo prefix to be ignored. The third form causes the 
default action, rejecting any undo prefix given. 
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A DETAILED EXAMPLE OF A FUNCTION DEFINITION 

The following example of a function definition for the 
string-search command uses many of the keywords described in this 
section: 

(defcom string-search 

Siinverse reverse-string-search 

^arguments {(search-string &string ^default 

&evai (get-search-string 

(search: numeric-prompt 
^String search") ) ) ) 

aproLogue search : command-prologue 
Sinumeric -argument & repeat 
^negative- function reverse-string-search 
Stepilogue search: command-epilogue 
Sicleanup search: command-cleanup 
(forward-search search-string)) 



The Stinverse keyword indicates that '^X'^S calls the 
reverse-string-search command. 



The ^arguments keyword indicates that '^S takes an argument 
named "search-string" (the string to search for), which defaults 
to calling the get-search-string function in order to get the 
string from the user by a prompt. 



The Stprologue keyword indicates that the prologue function 
named "search: command-prologue" runs before the first call of the 
forward-search command. In this example, the prologue function 
returns a cons of the number 0 and a mark set at the place from 
which the search began. 



The Scnumer ic-argument keyword indicates that ESC N calls 
the forward-search command N times. 



The &negative-f unction keyword indicates . that ESC -N ^S 
calls the reverse-string-search command, with a numeric argument 
of N. 
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The Stepilogue keyword indicates that the epilogue function 
named "searchicommand-epilogue" runs after each call of the 
forward-search command. In this example, the epilogue function 
does various bookkeeping operations for the forward-search 
command, deciding whether the command should continue or not. 
When the search fails, it aborts the command. The epilogue 
function is called with three arguments, which are as follows: 

prologue-info: 

in this example, whatever the &prologue function 
returns, which is a cons of a number and a mark; used 
by the epilogue function to store the iteration count. 

result: 

in this example, whatever the forward-search function 
returns, which is non-nil if the search was successful; 
used by the epilogue function to decide whether to let 
the function continue or not. 



lastp: 

in this example, non-nil if this- is the last iteration 
of the forward-search function; used by the epilogue 
function to decide whether to set a gratuitous mark if 
the search failed. 

The Stcleanup keyword indicates that the cleanup function 
named "search: command-cleanup" runs when the forward-search 
command is aborted. In this example, the cleanup function 
decides whether the forward-search command should go back to the 
beginning or not. The cleanup function is called with one 
argument, prologue-info, which is modified by the epilogue 
function as described above. 



The forward-search command is the actual code in this 
function definition of the string-search command. In this 
example, it's just one function call, but it could be several. 



You should note that most of the keywords are interpreted by 
the Emacs command loop. This means that they can be ignored when 
a command is called directly as a function, as it is in extension 
code. The main exception to this is the Starguments keyword. 
This keyword sets up an argument list for the function, so the 
function requires that those arguments be given explicitly in the 
function call. 



In the example above, this means that calling string-search 
is equivalent to calling forward-search, because all 
string-search does is call forward-search with its arguments. 
All of the other functions are executed before or after 
forward-search is executed, without its knowledge. 
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SECTION 4 



LDEBUG MODE 



Emacs LDEBUG mode (Lisp Debug) provides an interactive Lisp 
environment designed for the debugging of Emacs extension code. 
Facilities are provided for tracing the Lisp stack, breakpointing 
code, and interacting with the native MacLisp trace facility. 
LDEBUG mode is specifically optimized for multiple-window 
interaction. 



LDEBUG BUFFER 

The heart of the LDEBUG mode facilities is the LDEBUG 
buffer. The buffer named LDEBUG , when created by Idebug mode 
(either in response to a breakpoint's being executed, a trapped 
Lisp error, or the explicit "Idebug" extended request), evaluates 
any Lisp form typed into it when carriage return is struck after 
it. The form must be on one line? an error occurs if the form 
has syntactic errors (e.g., miscounted parentheses). The result 
of the evaluation is placed in the LDEBUG buffer on the next 
line, following the sign "=>", which indicates the result of such 
an evaluation. The Lisp variable is set to the result of 

each successive evaluation, as at raw Lisp top level; this may be 
used to reference the last printed result. 



Random Lisp forms such as "(+ 2 3)" or "current-buffer" can 
be typed at LDEBUG buffers, and the resulting buffer contents 
will in effect be a dialogue of an interaction with Lisp. Such 
buffers are often dprintable for later perusal. The values of 
variables can be set by evaluating the normal Lisp setq form, 
e.g., (setq var (+ foo 27)). As lines are placed into the LDEBUG 
buffer by the LDEBUG facility, the window (if any) containing it 
scrolls, if necessary. 
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Lisp values "printed" into the LDEBUG buffer are by default 
limited in length to ten and depth to six. The values of the 
option variables "Idebug-prinlength" and "Idebug-prinlevel" can 
be set to alter these defaults. The default input and output 
radices are both 8: these can be altered as the option variables 
"Idebug-ibase" and "Idebug-base" . As with ESC ESC, 
represents elements deeper than the depth limit and 
elements longer than the length limit. 



Most- Emacs requests can be used in LDEBUG buffers; they are 
in Lisp Debug mode, which is an extension of ordinary Lisp mode, 
with requests differing as detailed below ► 



EMACS AND LISP DEBUG MODE 

The Idebug (ESC X Idebug CR) extended request can be invoked 
at any time, in the usual way Emacs extended requests are 
invoked. It places Emacs in the LDEBUG buffer as described 
above,, and also sets up a system of Lisp error handlers "under" a 
new invocation of the Emacs request loop. Should any Lisp error 
occur while these handlers exist, the LDEBUG buffer is entered, 
placed on display if not already on display, the terminal's bell 
is beeped, and the Lisp error message is entered in the LDEBUG 
buffer. You are then at a "second (or greater) level" of LDEBUG, 
similar to being at Multics command level when an error occurs. 
The level number is part of the message entered in the LDEBUG 
buffer. 



Recursive (level, greater than 1) LDEBUG buffers can be 
released (aborting all executing code between the LDEBUG level 
being released and the previous level) via the ESC G 
( Idebug-return-to-emacs-top-level) request, the analogue of the 
Multics release command. It beeps and types "$g" in the LDEBUG 
buffer. The value of the variable Idebug-level tells the current 
level of LDEBUG buffers. 



ESC P (for proceed) is the analogue of the Multics start 
command? more about its meaning for each different type of entry 
to an LDEBUG buffer is described below. In general, it restores 
the buffer and window from which the LDEBUG buffer entered. 
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ERROR TRAP ENTRIES TO LDEBUG 



When an error trap entry to the LDEBUG buffer has occured, 
the Lisp stack can be traced via the ESC T ( Idebug-trace-stack) 
request, and the value of variables can be inspected simply by 
typing their names (since they are Lisp forms) to the LDEBUG 
buffer* For this to work most effectively, at least one level of 
LDEBUG should be in the stack before the error is encountered. 



A value can be returned to the Lisp error handler by typing 
it on a line, and instead of ending the line with carriage return 
(which would evaluate and "print" the result), ending it with ESC 
P. Lisp error handlers often want a list of the value to replace 
some erroneous value. For instance, in the following dialogue, 
an LDEBUG trap was entered because of the unbound variable 
"stuff": the programmer returned the symbol "value- i -wanted" as 
the intended value of the unbound variable: 



(myfun huff stuff) 

Lisp breakpoint unbnd-vrbl at level 1 in buffer LDEBUG: 
lisp: undefined atomic symbol stuff 

(' value- i -wanted ) $p 

All correctable Lisp error breakpoints accept a retry value to be 
used to retry the failing operation? the undefined function 
breakpoint ( "undf-f nctn" ) also accepts a list of a new value, in 
this case a function to be used instead. 



The "$p" is always printed by ESC P, to remind the user of 
the $p which is used in raw Multics MacLisp to restart breaks. 
ESC P can also be used alone on a line (i.e., no value to be 
returned preceding it) to restart a break and let Lisp*s default 
action occur. 



ESC G can be used as usual to release a level of errors to 
the next lower LDEBUG level; (conmiand-quit ) does not release 

past LDEBUG levels. 
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CODE BREAKPOINTS 



Breakpoints can be set in interpreted extension code being 
debugged by typing ESC & in a Lisp Mode buffer with the cursor at 
the point in some function being debugged where you would like 
this break set. The LDEBUG mechanism creates this breakpoint by 
putting a call to a tracing function ("%%") in the code in the 
buffer, and evaluating the function definition it is looking at. 
This break code is left in the function to let you know that it 
is there: it includes a break, number (they are assigned 
sequentially) to which this breakpoint can be referred by 
requests- yet to be described*^ 



You should be in at least one level of LDEBUG buffers before 
setting a break: thus, you should have said "ESC X Idebug CR" 
some time before setting breaks » 



Having set a break, you can run the code being debugged. 
When the breakpoint is entered, the LDEBUG buffer is entered at a 
new higher level.. A message of the form: 

31^33 ir 4. in function test fun 

is put in the buffer, and the LDEBUG buffer is put on display. 
As in all LDEBUG buffers, arbitrary forms can be evaluated 
(including inspecting variables), and ESC T can be used to trace 
the Lisp stack. Again, ESC G releases a level of LDEBUG buffers. 



ESC P is used to restart code breakpoints as well. A given 
breakpoint can be set for some number of proceeds (i.e., "3" 
means proceed, and proceed this breakpoint the next two times it 
is encountered automatically) by giving that number as a numeric 
argument to ESC P (i.e., ESC 3 ESC P) . A message indicating the 
number of proceeds is inserted in the LDEBUG buffer. ESC P 
should be used alone on a line (i.e., no retry value) when 
restarting code (or trace) breaks. 



When in a code break, ESC R ( Idebug-reset-break) resets the 
current breakpoint, before restarting or releasing. The break 
code is removed from the function definition (visibly, if it is 
on display), and the function definition is reevaluated. ESC R 
with a numeric argument can be used to reset a break by number. 



In an LDEBUG buffer, ESC L ( Idebug-list-breaks) lists all 
the known code breakpoints: their numbers, the function in which 
each break appears, the buffer that function appears in, and the 
status of each break. 
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The source for the current breakpoint can be shown by 
issuing the request ESC S ( Idebug-show-bkpt-source) . It is 
placed in an available window (if in multiple window or 
pop-up-window mode), and the cursor is moved to the break code. 
Use '^XO to get back, or, in one-window mode, '^XB CR. 



During function breakpointing, to determine where the editor 
was (i.e., what was the current buffer, and where was the current 
point) at the time the breakpoint was encountered use ESC ^S 
(Idebug-display-where-editor-was) • It selects the appropriate 
buffer, moving the cursor to the point in it where the current 
point was when the breakpoint was taken. If the buffer is 
already on display in some window (or pop-up windows are being 
used), that window is selected, and ^XO returns you to the LDEBUG 
buffer for further probing or restarting. In one-window mode, 
the correct buffer is switched to, and ^XB gets you back. If the 
current point is moved by you explicitly (i.e., via normal Emacs 
requests) while visiting the buffer where the breakpoint was 
taken, it has its new position when the breakpoint is restarted. 
This is analogous to setting a variable before restarting with 
usual Multics debugging. 



Using two or three windows to contain the LDEBUG buffer, the 
breakpoint source (function being debugged), and the buffer the 
functions being debugged are working on, is highly effective. 



FUNCTION TRACING WITH LDEBUG 

The standard MacLisp trace package can be used while in 
Emacs; extensibility features of the former allow LDEBUG to take 
control of the trace output and breakpointing provided by it. 



All the facilities of the standard trace package can be 
used, by invoking trace from ESC ESC minibuffers. The trace 
package allows tracing of entries and exits to functions, 
arguments, and return values, and breakpoints when functions are 
entered. Some sample forms to trace the function testfun are 
given here: these are in Lisp syntax, and can be typed as such 
to LDEBUG mode. When typed to an ESC ESC minibuffer, the outer 
set o£ parentheses should not be supplied. 

(trace testfun) 

Traces the input arguments and returns value of testfun 
each time it is invoked. 

(trace (testfun break (< x 3))) 

Traces input and returns value of testfun, enters a 
breakpoint when entered and x (x can be an argument to 
testfun) is less than 3. 
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(trace (testfun break t)) 

Same, but enters a breakpoint at every entry to 
testfun, 

(trace (testfun entry (a b) exit (c))) 

Traces, input arguments and returns value. Also prints 
out the values of a and b when testfun is entered and 

the.' value of c when it is exited. 



The general syntax: of trace invocations is (brackets 
indicate optional clauses r and angle brackets are syntactic 
variables) r 

(trace <fnname-or-clause-l> ... <fnname-or-clause-n>) 

where <fnname-or-clause> is either a function name to be traced 
for input arguments only and return value, or: 

(<fnname> [break <break-condition>] [entry (<entry-vals>) ] 

[exit (<exit-vals>) ] ) . 

When a function is traced within Emacs (it is not 
recommended to trace internal Lisp or Emacs primitives, and no 
part of the redisplay should be traced in this way), trace output 
for entry and exit tracings are placed (and scrolled) directly 
into the LDEBUG buffer if it is on display; if it is not on 
display, this output is put in the LDEBUG buffer, and locally 
displayed as it is produced. The line of dashes and asterisks of 
local displays is not produced, as it cannot be known when the 
end of trace output has been reached. Thus, traced functions 
invoked from the minibuffer may often leave the cursor in the 
minibuffer awaiting clearing of the local display via linefeed or 
'^L. 

Trace output generally looks likes 

(3 enter testfun (3 5 (a . b)) /|/| (4 5)) 

The indentation level gives the depth in currently active traced 
functions. The "3" is the recursion depth of the given function 
(e.g., testfun) being traced. The "enter" is the type of trace 
(enter vs. exit), (3 5 (a . b)) is the list of arguments (in 
this case, three arguments). The /|/| sets off the entry values 
and exit values optionally selectable by the entry and exit 
keywords in the trace-invoking form. Exit traces look like: 

(3 exit testfun 17) 
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If trace is used to set an entry breakpoint, the LDEBUG 
buffer is trapped to at the time the traced function is entered, 
in a way very much like a Lisp error break to LDEBUG. A message 
such as: 

Entry breakpoint to function testfun 

is printed into the LDEBUG buffer, and the terminal beeped. As 
with LDEBUG code breaks, ESC G releases, ESC P restarts, ESC R 
resets, and ESC ^S shows where the editor was at the time the 
break was taken. When in entry breakpoints to interpreted 
functions, the arguments can be inspected by name, ESC T can 
trace the Lisp stack, but unless *rset t mode was in effect 
(setting up an LDEBUG level does this automatically), trace 
information may not be present. 



It is not necessary to have invoked Idebug before invoking 
trace in Emacs; LDEBUG is invoked automatically if an attempt is 
made to use trace in Emacs. If some critical mechanism is being 
debugged and normal trace handling (i.e,, breakpointing/tracing 
to user_i/o from Lisp, not the Emacs handling just described) is 
necessary, the variables trace-printer and trace-break-fun should 
be made unbound (e,g., ESC ESC makunbound * trace-printer ) before 
the first reference to trace in a given invocation of Emacs, 
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SECTION 5 



WRITING EMACS TERMINAL CONTROL MODULES (CTLS) 



Support of video (and printing) terminals in Emacs is 
accomplished via terminal-dependent modules known as CTLs. There 
are about two dozen supplied CTLs. Emacs attempts to locate an 
appropriate CTL by using the regular search rules, based upon the 
terminal type maintained by Multics, and optional Emacs control 
arguments. The list_emacs_ctls command is provided to list all 
the known terminal CTLS. 



To support a type of terminal not supported by a supplied 
CTL, you must write a new CTL. A CTL is written as a Lisp source 
program, named TTYTYPE.ctl.lisp, where TTYTYPE is the name of the | 
terminal type to be supported. If this terminal type is in your j 
site's Terminal Type File (TTF), the name chosen should appear 
the same as it appears in the TTF, except that the name of the 
CTL should be all lowercase (Emacs lowercases terminal types when 
looking for CTLs). 



CTLs are usually written by example from supplied CTLs. 
Personnel with no knowledge of Lisp at all have achieved this 
successfully. Once the CTL is written, it must be compiled 
before it can be used. Compilation is performed via the Lisp 
compiler, Icp. A typical command line to compile a CTL is: 

Icp super58.ctl | 

This produces an object segment, super58.ctl, * 
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Two control arguments for setting the terminal type are 
recognized by Emacs when given as a command line argument. These 
are: 

emacs -terminal_type STR or emacs -ttp STR 

where STR is your terminal type. The value of STR 
can be any recognized editor terminal type. The CTL 



I is found via the user's search rules. The terminal 

I type given by STR is set only for the current 

I invocation of Emacs r in subsequent invocations, Emacs 

I checks your Multics process terminal type if you have 

|, not respecified it with -ttp.. 



emacs -query 

Emacs queries the user for the terminal type without 
checking the Multics terminal type first. The answer 
you give may be any STR accepted by the -ttp option. 



Added names and links can be used to support many TTF 
terminal types via one CTL. When Emacs is given a terminal type 
(either from Multics Communication System or the -ttp control 
J argijment) for which it cannot find a CTL, it asks you if you want 
I to see the list_emacsj:tls list of known terminal CTLs. 



The most effective method of writing a new CTL is to take 
one that was written for a similar terminal and modify it. 
Almost all of the extant CTLs were written in this way. The 
sources are Lisp source segments, generally one or two printed 
pages long. Good starting points are: 

a vip7200 ..ctl. lisp, typical of terminals that do not have 
the ability to insert or delete lines or characters. 

» vip7800 .ctl. lisp, typical of terminals that do have 
these abilities. The two facilities are independent, 
either one, both, or neither may be present, although 
use of terminals without insert/delete lines at less 
than 1200 baud may be found to be unacceptable. 



The interfaces (function definitions) in a CTL are 
standardized. They have the same names in all CTLs. The Emacs 
screen manager calls these interfaces anonymously after the 
appropriate CTL has been loaded. The interface DCTL-init is 
called at Emacs start-up time; it has the responsibility of 
setting various flags, and initializing the terminal. It should 
contain the statements: 
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(setq 



idel-lines-availablep t) 
if the terminal can insert/delete lines. 



(setq 



idel-lines^availablep nil) 
if it cannot. 



(setq idel-chars-availablep t) 

if the terminal can insert/delete/ characters. 

(setq idel-chars-availablep nil) 
if it cannot, 

(setq tty-no-cleolp t) 

if the terminal has no clear-to-end-of-line facility. 
Such terminals are generally unsatisfactory at speeds 
less than 2400 baud. 

(setq region-scrool-availablep t) 

if the terminal has region scrolling (see below). 

(setq screenheight N.) 

where N is the number of lines on the screen (note 
the dot after the N). 

(setq screenlinelen M.) 

Where M is one less the number of characters in a 
line on this terminal . Again, note the dot. 

(setq tty-type ^TYPENAME) 

Where TYPENAME is a word like "superBS" that 
identifies the terminal type. 



At the time DCTL-init is invoked, the variable ospeed is set 
to the speed of the communications line in characters per second 
(e.g., 1200 baud is 120 chars/sec). This can be used to perform 
padding calculations. This value is usually computed from the 
line speed maintained by the Multics Communication System. The 
-line_speed control argument can be used to specify terminal 
speed for users logged in via the ARPANET. 



In addition, you can use the -page_length or -line_length | 
control arguments to override the terminal controller defaults | 
for page and line lengths. | 
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Also before DCTL-init is invoked, the variable 
given-tty-type is set to the name by which the CTL was loaded 
with the "ctl" suffix stripped. This variable can be used in 
DCTL-init (and elsewhere) to enable and use different features of 
a terminal dependent on the name used to reference that terminal. 
To ensure that given-tty-type is different for various versions 
of a terminal, give the additional varieties of the terminal as 
added names on the. CTL segment. For example, the names 
vtlOOw.ctl, vtlOOws.ctl, and vtlOO.ctl are all associated with 
the same CTL segment. This allows the VTIOO CTL to distinguish 
between various screen widths and heights, by using the value of 
given-tty-type.. The: "eq" predicate (i.e., (eq given-tty-type 
'dd4000)) can be used to check the value of this variable. The 
variable tty-type should be set by the CTL to a generic terminal 
type, e.g. , vtlOO for all varieties of VTIOO, as opposed to the 
type given in given-tty-type. 

The following functions are available to the CTL writer: 

» Htyo takes one argument, a number (fixnum), and outputs 
that number as ASCII data. For example, (Rtyo 141) 
outputs an "a", and (Rtyo 33) outputs an ESC. 

» Rprinc takes one argument, a character string, and 
outputs it. For example, (Rprinc "]I") outputs a right 
bracket and an I. 

Both of these functions buffer their output until the Emacs 
screen manager dumps this buffer. This is always done at the end 
of any redisplay at all, and after DCTL-init is called. 



The CTL writer must maintain the values of the special 
(global) variables X and Y relative to a zero origin screen 
position where the cursor was left. In return, you get to 
inspect these variables to do positioning optimization. 



The CTL writer must provide the following interfaces to be 
called by the Emacs screen manager: 

a. DCTL-init (no arguments). Must set the flags listed 
above, initialize the terminal (if necessary), clear 
the terminal screen, and leave the cursor at position 
(0, 0) (home). 



5-4 



CJ52-01 



s DCTL-posit ion-cursor (two arguments, a new X position 
and a new Y position). Move the terminal's cursor to 
the given position. Position 0, 0 is defined as the 
upper left hand corner of the screen. This function 
must check the variables X and Y, and output no 
characters if the cursor is known to be already at the 
desired position. Otherwise, it must use the values of 
X and Y to determine what type of motion is necessary, 
output characters to move the cursor, and update X and 
Y to the input parameters (the delay of the buffered 
output is not an issue). 



Typically, DCTL-position-cursor determines which is the 
optimal movement based upon the relative positions of the cursor 
and the desired position. For terminals that have many forms of 
cursor movement, some combination of backspaces, linefeeds, and 
carriage returns may be adequate to effect some forms of cursor 
movement. Sometimes the sequences generated by the arrow buttons 
on the terminal may be used for relative positioning. Just about 
all terminals include some form of absolute positioning. The 
choice of optimal cursor positioning should be based upon which 
will output the fewest characters to effect the desired move. | 
See hp2645.ctl.lisp for an example of a very well optimized | 
cursor positioner. 



One useful trick in the writing of DCTL-position-cursor is 
the use of recursion. See adds980 .ctl. lisp for an example. If | 
you choose to use terminal tabs, then your DCTL-init must set I 
them, and you must take care not to clear them. No supplied CTLs 
(other than the extremely special-case printing terminal 
controller) use tabs. 

B DCTL-di splay-char-string (cne argument, a character 
string to be displayed). Must output this character 
string to the terminal at the current assumed cursor 
position. The string is guaranteed to contain no 
control or other nonprinting characters, and each 
character in it is guaranteed to take up only one print 
position. Be careful to update cursor position after 
printing the string; the lisp function stringlength may 
be used to ascertain the length/printing length of the 
string. 
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B DCTL-kill-line (no arguments). Clear the line from the 
current assumed cursor position to the end of the line, 
J-gave the cursor at that original assumed position. 
Most video terminals have a clear-t.o-end-of-line 
feature? it should be used here if available. Some 
terminals do not, so the flag tty-no-cleolp must be set 
to indicate this and DCTL-kill-line not defined. If 
this flag is set, the Emacs redisplay simulates 
cIear~to-end-of-line by overwriting portions of lines 
with spaces » This technique is tedious but necessary. 

m GCTL-cIear-rest-of-screen (no. arguments).. Clear the 
screen from the current assumed cursor position to the 
end* Leave the cursor where it was supplied. Some 
terminals have a "clear whole screen" function, but not 
clear to end of screen. Currently, you can use the 
clear whole screen function. If your terminal does not 
even have a. clear-whole-screen function, it is probably 
not worth using with Emacs, If you choose to use tabs 
in cursor positioning, be wary of clearing them via 
this function. 



Those are all the required functions. Some terminals 
require control sequences to change modes between normal Multics 
operation and operation within Emacs, (For example, a terminal 
might be switched between line-at-a-time transmission and 
character-at-a-time transmission.) Yet other terminals might use 
features during the operation of Emacs that should be 
disabled/reset when using Multics. (For example, the Digital 
Equipment Corporation VTIOO uses "scroll" regions to simulate 
insert/delete lines. However, if a scroll region exists, it 
makes parts of the screen unusable when using Multics.) It is 
possible and quite common to switch between Multics and Emacs by 
using the ATTN key and the program_interrupt command. In such 
cases, the terminal is in the wrong mode at various times. If 
the terminal for which you are writing a CTL exhibits this 
behavior, you should add the following statements to DCTL-init: 

(setq DCTL-prologue-availablep t) 

to specify that certain functions must be performed 
each time Emacs is entered from Multics, 

(setq DCTL-epilogue-availablep t) 

to specify that certain functions must be performed 
each time Multics is entered from Emacs. 
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In addition, you must then supply the following two functions: 

B DCTL-prologue (no arguments). Perform any operations 
that are required when Emacs is entered from Multics. 
This function is invoked immediately after DCTL-init is 
called and after Emacs is reentered after a QUIT via 
either the Multics program_interrupt or start commands. 

B DCTL-epilogue (no arguments). Perform any operations 
that are required when Multics is to be entered from 
Emacs, This function is invoked immediately before 
Emacs is exited when the ^X'^C (quit-the-editor ) request 
is invoked, and immediately before Emacs is suspended 
when the ^Z^^Z (quit) request is invoked or the ATTN key 
is hit on the terminal. 



If you have stated that insert/delete lines is available, 
via setting the flag idel-lines-availablep to t, you must supply 
the following two functions. If you set this flag to nil, you 
need not write these functions: 

B DCTL-insert-lines (one argument, a number of lines to 
be inserted). Open up the given number of lines on the 
screen. There are that many blank lines (created by 
DCTL-delete-lines) at the bottom of the screen at the. 
time this function is invoked. The cursor is at 
position 0 of some line at the time DCTL-insert-lines 
is invoked. It must push the contents of that line 
down the supplied number of lines, leaving the cursor 
in the same place, and the line the cursor Is on and 
the n-1 succeeding lines blank. 

B DCTL-delete-lines (one argument, a number of lines to be 
deleted). Delete from the screen the supplied number 
of lines, starting with the line the cursor is on and 
proceeding downward. The cursor is to be left in the 
same place it was given. That many blank lines are 
assumed to be pulled up on the bottom of the screen. 



If the flag idel-chars-availablep is set to t, indicating 
that insertion and deletion of characters is available, the 
following two functions must be supplied; 

B DCTL-insert-char-string (one argument, a character 
string to be inserted at the current assumed cursor 
position). Insert the character string supplied at the 
current cursor position. Push to the right all 
characters at, and to the right of, the current cursor 
position. There are only blanks on the screen in the 
region being pushed off. Leave the cursor (and so 
updat) after the last character of the inserted string. 
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B DCTL-delete-chars (one argument, the number of 
characters to be deleted) . Physically delete from the 
screen the supplied number of characters, starting with 
the character at the cursor and on the right. Move all 
characters to the right of these characters that many 
positions to the left. That many blanks are assumed to 
be moved in from the right edge. Leave the cursor 
where it was supplied. 



Some terminals, such as the DEC VTIOO and the Human Designed 
Systems Concept 100 r offer a feature called region-scrolling, 
which allows, groups of lines to be moved up or down at: once 
without the two-step operation of delete-lines followed by 
insert-lines. The Emacs redisplay can take advantage of this 
featurer the result is scrolling without the "jumping 
minibuffers" and pulling and pushing associated with window 
management via insert/delete lines. If your terminal has region 
scrolling, do not define DCTL-insert-lines and DCTL-delete-lines 
for your terminal.. Instead, setq the special variable 
region-scroll-availablep to t at DCTL-init time. The following 
two functions must then be defined: 

B (defun DCTL-scroll-up-region (amount bottom).,.) 

This operation will be invoked with the cursor at the beginning 
of some line of the screen- It defines an operation affecting a 
region that includes the current line down to, but not including, 
the line designated (by number, in the second argument) as the 
<bottom> (where the first line on the screen is 0). This region 
is scrolled up by <amount>, where amount is the number of lines 
given as the first argument. The cursor is left where it is, at 
the beginning of the newly scrolled-up current line. So, in 
efect, where <si2e> is the size of the region (in lines), the 
lower <si2e minus amount> lines of the region are moved up to 
become the topmost <si2e minus amount> lines of the region. The 
last <amount> lines of the region are left blank, and the 
contents of what were the first <amount> lines depart 
irretrievably from the screen. In the following example, assume 
C represents the cursor and call: 

(DCTL-scroll-up-region 2 7) 



Before 


After 


Foo 


Foo 


Bar 


Bar 


CQuux 


CLuux 


Truux 


Buux 


r. 1111V 




Buux 




Bears 
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Cubes 
Bmacs 



Cubes 
Bmacs 



The second function is: 

a (defun DCTL-scroll-down-region (amount size)...) 

This operation will be invoked with the cursor at the beginning 
of some line of the screen. It defines an ^operation affecting a 
region that includes the current line down to, but not including, 
line number <bottom>, where the first line on the screen is 0. 
The size of this region, in lines, is <size> (the second 
argument). This region is scrolled down by <amount> (the first 
argument) lines, and the cursor left where it is at the beginning 
of the current line of the screen. So, in effect, the upper 
<size minus amount> lines of the region are moved down to be the 
bottommost <size minus amount> lines of the region. The first 
<amount> lines are left blank, and the contents of what were the 
last <amount> lines departs irretrievably from the screen. 

Again, in the following example assume C represents the 
cursor and call: 

(DCTL-scroll-down-region 2 7) 



Before 


After 


Foo 


Foo 


Bar 


Bar 


CQuux 


C 


Truux 




Luux 


Quux 


Buux 


Truux 


Bears 


Luux 


Cubes 


Cubes 


Emacs 


Bmacs 



Writing a CTL usually involves editing an existing one, 
trying it, modifying it, and ' iterating until it is solid. You 
use the -ttp control argument many times to switch back and forth 
between printing terminal mode and the new CTL when logged in 
from the terminal on which the CTL is being developed. For 
terminals with insert/delete features, it may be convenient to 
debug the CTL first without these features (claim they are not 
there in the DCTL-init), and add them later. Similarly, you are 
encouraged to write a better DCTL-position-cursor once you have 
one that works at all, for the convenience of editing the CTL 
with Emacs substantially reduces the effort of improving it. 
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For some terminals, padding may be necessary for some 
operations at some or all line speeds. If terminal behavior 
appears random, or garbage is left on the screen after a '^L or 
^K, this may be the problem. Check the manual for your terminal 
about padding requirements. It may be convenient to define a 
function called DCTL-pad, which takes a number of microseconds or 
milliseconds as an argument, and issues enough pad characters to 
perform this padding. (Rtyo 0) or (Rtyo 177) are common, but 
check your terminal manual f.or what your terminal expects; (Rtyo 
0) generally works. The variable ospeed gives the line speed in 
characters, per second,, for use in such calculations. Getting the 
padding right may involve quite a bit of tinkering on some 
terminals r one proven method in cases where padding is felt to be 
a problem is to specify a very large amount of padding (e.g., a 
second) and cut it down until it works* See dd4000.ctl.lisp for 
an example of terminal padding. 



The Lisp special forms cond and do are used heavily in CTLs. 
Since Emacs environment macros (do-forever, if, etc) should not 
be used in CTLs, the native Lisp forms are necessary. Here are 
the descriptions of cond and do: 

(cond ((= this that) ( thingl) ( thing2) ) 
( ( > a b ) ( sec ond ) (third) 27 ) 
( (< c 15) (other) ) 
(t (best 5) (chance))) 

means: 

"If- this equals that, call thingl of no arguments, then call 
thing2 of no arguments, and return as the value of the cond 
the value returned by thing2. Otherwise, if a is greater 
than b, call "second" with no arguments, then call "third", 
and return 27 as a value. Yet otherwise, if c is less than 
15 (all numbers octal), return the value obtained by 
applying "other" to no arguments. If none of the above are 
true, call "best" with an argument of 5, and then return the 
value obtained by calling "chance" with no arguments." 



5-10 



CJ52-01 



The cond special form is much like PL/I ' s 
if ( . . . . ) then do; 



end; 
else 

end; 
else 



end; 

else do; 



end; 



» » m » 



) then do; 
) then do; 



The format of Lisp "do" used in CTLs to iterate is: 

(do VARIABLE INITIAL-VALUE REPEAT-VALUE TEST forml form2 
forms., ) 



It is equivalent to PL/I*s: 

do VARIABLE = INITIAL- VALUE 
repeat REPEAT-VALUE 
while TEST); 



forml ;form2; ... 



end; 



which, itself, is equivalent to: 
1: 



VARIABLE « INITIAL- VALUE; 
if TEST then go to e; 
forml ;form2; ... 
VARIABLE = REPEAT-VALUE; 
go to 1; 



e: 



The variable VARIABLE is locally defined inside the do. It may 
be used in the forms inside the do, in the "end test" TEST, and 
in the repeat value REPEAT- VALUE . 
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APPENDIX A 



THE BACKQUOTE FACILITY 



The backquote facility defines two characters with special 
syntax to the Lisp reader: backquote — ASCII code 140) and 
comma (, — ASCII code 54). These two "macro characters'* can be 
used together to abbreviate large compositions of functions like 
cons, list, list*, and append. It is typically used to specify 
templates for building code or other list structure and often 
finds application in the construction of Lisp macros. 



If you are in Emacs, backquote is automatically defined 
correctly for you. ESC-ESC, LISP mode, and LDEBUG mode all 
handle it properly. If you write extension code that uses 
%include e-macros. incl.lisp (as all extension code should), 
backquote is defined properly for you as well. If you are 
writing Lisp code other than Emacs extensions, your program 
should include the form (%include backquote) before the first use 
of backquote. 



Backquote has a syntax similar to that of quote (' — ascii 
47). A backquote is followed by a single expression. If the 
expression does not contain any use of the comma macro character, 
then the form will simply be quoted. For example: 

Ma b c) -> (quote (a b c)) => * (a b c) 



The comma macro character can only be used within a form 

following a backquote. Comma also has a syntax like that of 
quote. The comma is followed by a form, and that form. is 
evaluated even though it is inside the backquote. For example: 



M,a b c) 



> 



(cons a (quote (b c) ) ) 
(cons a '(be)) 



> 



Ma ,b c) 



> 



(list* (quote a) b (quote (c))) 
(list* 'a b Mc)) 



> 
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""(a b ,c) => (list (quote a) (quote b) c) 
=> (list 'a 'be) 

^ (a • ,rest) *> (cons (quote a) rest) 
=> (cons 'a rest) 

Thus, to write the common macro "push" using backquote, proceed 
from the standard definition: 

(defun push macro (form) 

(list 'set(i (caddr form) (List *cons (cadr form) (caddr form 

tor 

(defun push macro (form) 

"•(setq , (caddr form) (cons , (cadr form) , (caddr form)))) 

Note how the code to build the macro's output code begins to look 
more like the output code itself* In fact, using let, you can go 
all the way to: 

(defun push macro (form) 

(let ((datum (cadr form)) 
(list (caddr form))) 
^ (setq ,list (cons , datum ,list)))) 

and produce very legible code. 



Backquote expands into forms that call cons, list, list*, or 
whatever other functions it deems appropriate for the task of 
constructing a form that looks like the one following the 
backquote, but with the values of the forms following the commas 
substituted in» 



If a comma inside a backquote form is followed by an at 
sign — ASCII code 100), then the form following the ",(§" 
should return a list. Backquote arranges that the elements of 
that list will be substituted into the resulting list structure. 
Frequently this involves generating a call to the append 
function. For example: 

^(,(§a b c) => (append a (quote (b c))) 
=> (append a ' (b c ) ) 

(a ,@b c) «> (cons (quote a) (append b (quote (c)))) 
=> (cons 'a (append b '(c))) 

^ (a b ,{ac) => (list* (quote a) (quote b) c) 
=> (list* 'a 'b c) 
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Similar to following the comma by an at sign is following 
the comma by a dot (. — ASCII code 56). The dot is a declaration 
to backquote telling it that the list returned by the form 
following the is expendable. This allows backquote to 

produce code that calls functions like nconc that rplac the list. 



Backquote examines the forms following the commas to see if 
it can simplify the resulting code. For example: 

^ (a b . ,(cons x y)) => (list* (quote a) (quote b) x y) 

=> (list* 'a 'b x y) 

Ma 3 ,b c ,17) => (list* (quote a) 3 b (quote (c 17))) 

=> (list* *a 3 b ' (c 17) ) 

''(a ,%b ,@nil) => (cons (quote a) b) 

=> (cons 'a b) 

(a ,,b ,@(nconc c d)) => (cons (quote a) (nconc bed)) 

=> (cons 'a (nconc b c d)) 



These examples should convince you not to depend on what the 
code that backquote expands into will look like. Backquote' s 
contract is specified not in terms of the code that it expands 
into but rather in terms of what that code produces when 
evaluated. A simple backquote might expand (,@a ,@nll-) into 
(append a *nil), but this cannot be used as a reliable way to 
copy a list since a sophisticated backquote (like this one) can 
optimize the copying away. 

It is sometimes useful to nest one use of backquote within 
another. This might happen when writing some code that will cons 
up some more code that will in turn cons up yet more code. The 
usual example is in writing macro-defining macros. When this 
becomes necessary it is sometimes difficult to determine exactly 
how to use comma to cause evaluation to happen at the correct 
times. The following example exhibits all the useful 
combinations: 

^Ma ,b ,,c /,d) 

=> (list 'list* "a 'be (list 'quote (list d))) 
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When evaluated once, this yields: 

(list* 'a b <c-at-time-l> ' (<d-at-time-l>][ ) 
Which when evaluated yields: 

(a <b-at-time"*2> «c-at-time-l>-at-time-2> <d-at-time-l>) 

Thus ""means never evaluate, " means evaluate only the second 
time, , means, evaluate both timesr, and ' , " means evaluate 
only: the first time^ 
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APPENDIX B 
QUICK REFERENCE 



The following functions, special forms, predicates, and 
global variables mentioned in this manual have been grouped below 
according to the uses they serve in extensions. Following those 
groupings is an alphabetized list that includes a brief 
description of each function, special form, predicate and global 
variable listed. The categories include: 

Buffers 

Calculations 

Catenation 

Character/Numeric Conversion 

Charscan Table/Characters 

Comments 

Comparison 

CTL 

Debugging 

Defining/Calling a Command/Function/Property 

Displays 

Error Handling 

Execution and Conditional Evaluation 

Files 

Killing 

List Processing/Cons 
Marks 

Minibuf f ers/Prompts 
Modes 

Modified Flag 

Multics Command Execution 

Point Position 

Searching 

Variables 

Whitespace 

Windows 

Miscellaneous 
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Buffers 



buf f er-c r ea t i on-hook 

buffer-destruction-hook 

buffer-entrance-hook 

buffer-exit-hook 

buf fer- kill 

bu f f e r -m i no r -mode s 

buf f e r-mod i f i ed- f lag 

buf f er-on-display-in-window. 

CAir r en t-buf fer 

cairren t-buf f e r-mode 

destroy-buf f er-contents 

display-buff er-as-printout 

dont-notice-modif ied-buf f er 

empty-buff er-p 

establish-local-var 

f ind-buf f er-in-window 

f ind-f ile-subr 

go-to-or-create-buf fer 

previous-buf f er 

read-only-f lag 

save-excurs ion-buffer 

3 e 1 e c t - bu f f s r - f i n d- w i ndo w 

select-buffer-window 

set-buffer-self-destruct 



Calculations 
*■ 



// 



Catenation 

apply-catenate 
catenate 



Character /Number Conversion 

*nopoint 
ascii 
base 
Ctol 

decimal-rep 

ibase 

ItoC 



Character Table/Characters 



charscan-table 

char set-member 

explode 

explodec 

get-char 

lef thand-char 

process-char 

search-back-f irst-charset-line 
search-back-f irst-not-charset-line 
search-char set-backward 
search-charset- forward 
search-for-f irst-charset-line 
search-for-f irst-not-charset-line 
sea rch-not-char set-backward 
search-not-charset- forward 



Comments 

comment-column 
comment-prefix 



Comparison 
< 
> 

alphalessp 
eq 

f ixp 

saroepnamep 



CTL 

DCTL-clear-rest-of -screen 
DCTL-delete-chars 
DCTL-delete-lines 
DCTL-di splay-char-string 
DCTL- epilogue 
DCTL-init 

DCTL- insert-char-string 

DCTL- insert-lines 

DCTL- kill-line 

DCTL-posit ion-cursor 

DCTL-prologue 

DCTL-sc roll-down-region 

DCTL-scroll-up-region 

Rprinc 

Rtyo 
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Debugging 

debug-e 

Idebug-mode-hook 



Def ininq/Callinq a Command/Funct ion /Property 

defcom 

defprop 

defun 

funcalL 

get 

process-char 
putprop 
set- key 

set-permanent-key 



Displays 

display-as-printout 

display-buff er-as-printout 

display-com-error 

di splay-com-er ror-noabort 

display-error 

display-err or-noabort 

display-error-remark 

end-local-di splay s 

full-redisplay 

in it-local-displays 

local-display-current- line 

local-di splay-generator 

local-di splay-generator-nnl 

redisplay 

redisplay-cur rent-window-relative 
view-region-as- lines 



Error Handling 

I add_error_code 
command-quit 
display-com-error 
display-error 
display-err or-noabort 
display-error-remark 

I error-table 



I 
I 



I 



error_table_ 

rsmf- or" ■t- 

report-error 
report-er ror-noabort 
ring-tty-bell 
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trace 

unwind-protect 



Execution and Conditional Evaluation 

and 
cond 

dispatch-on-current"char 
dispatch-on-lef thand-char 
do 

do-forever 

do-times 

eval 

funcall 

go 

if 

if-at 

if -back-at 

mapc 

or 

prog 

progl 

prog2 

progn 

return 

save-excursion 

save-excurs ion-buffer 

save-excursion-on-error 

stop-doing 

unwind-protect 

without-modifying 

without-saving 



f ind-f ile-subr 
f pathname 
read-in-f ile 
write-out-f ile 
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Killing 

buffer-destruction-hook 

buffer-kill 

delete- white- sides 

delete-window 

destroy-buffer-con tents 

killsave-string 

kill-pop 

kill-ring-top 

rotate-kill-ring 

set-buffer-self-destruct 
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w i pe-po i n t -ma r k 
without-saving 



List Processing/Cons 
append 

apply-catenate 

car 

cdr 

cons 

explode 

explodec 

list 

list* 

memg 

nconc 

n reverse 

reverse 

replaca 

replacd 



Marks 

der-wahrer-mark 
go-to-mark 

mark-at-current-point-p 

mark-on-current-line-p 

mark-reached 

mark-same-line-p 

point-mark-to-string 

point>markp 

release-mark 

set-mark 

wipe-point-mark 

with-mark 



Minibuf fers/Prompts 

last-mini buffer- response 
minibuf fer-response 
minibuf fer-clear 
minibuf fer-print 
minibuf fer-pr in t-noclear 
yesp 



Modes 



aim-mode-hook 
assert-minor-mode 



buf f er-minor-modes 

current-buffer-mode 

fill-mode-delimiters 

f ortran-mode-hook .. 

Idebug-mode-hook 

lisp-mode-hook 

ma i 1-mode-hook 

negate-minor-mode 

pll-mode-hook 

rma i l-mode~hook 

text-mode-hook 

Modified Flag 

buf f er-modi f ied-f lag 

don t-not ice-modi fied-buffer 

read-only- flag 

without-modifying 



Multics Command Execution 

comout-get-output 
e cline 



Point Position 
at 

at-beginning-of-buf f er 
at-end-of-buf f er 
at-white-char 
back-at 
.bolp 
cur-hpos 
curchar 
eolp 

f irstlinep 
go-to-hpos 
go-to-mark 
if-at 

if-back-at 

lastlinep 
looking-at 

mark-at-current-point-p 
next-line 

point-mark-to-string 

point>markp 

prev-line 

save-excursion 

save-excursion-on-error 



Searching 



charscan-table 

forward-search 

get -search-string 

regexp-search 

r ever se-regexp- search 

search-back- £irst-char set-line 

search-back-first-not-char set-line 

search-char set- back ward 

search-char set-forward 

search-failure-annunciator 

search- for-first-char set-line 

search-f or- first-not-char set-line 

sea rch-not-char set-backward 

search-not-char set-forward 



Variables 

de£var 

establish-local-var 

let 

register-local-variable 
setg. 



Whitesoace 

at-white-char 

delete-white-sides 

format-to-col 

line-is-blank 

skip-back-to-whitespace 

skip-back-whitespace 

skip-back-whi tespace-in-line 

skip-over-whitespace 

skip-over-whi tespace-in-line 

skip-to-whitespace 

tab-equivalent 

whi tespace-to-hpos 

Windows 

buffer-on-di splay- in- window 
delete-window 
find-buffer- in- window 
nuwindows 

redi splay"Currsnt""window-relat i ve 
select-buf fer-f ind- window 
select -buffer-window 
select-window 
selected- window 
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window-ad just- lower 
window-ad just-upper 
window- info 



Miscellaneous 

close-line-hook i 

env-dir 

ESC 

fill-mode-delimiters 

insert-string 

ma k nam 

nil 

NL 

not 

null 

null-stringp 
print 

process-dir 

read-f rom-string 

ring-tty-bell 

stringp 

symbolp 

t 

yesp 



Bach item described below also has a note that indicates 
what type of item it is. The item types ares 

Native Lisp function, variable, predicate, or special form 

Emacs environment function, variable, etc. 

CTL functions, to be defined by CTL writer, called by 

Emacs Redisplay, and not called by extension code under 

any circumstances. 



* Lisp function 

takes any number of arguments, which are expected to be 
fixnums (integer numbers), and returns their product. 

♦nopoint Lisp global variable 

when bound to anything but nil, causes decimal numbers to be 
converted to their printed representation without a trailing 
decimal point. 

+ Lisp function 

adds any number of fixnum arguments. 
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Lisp function 

subtracts all of its (fixnum) arguments but the first from 
its. first argument. With two arguments, it simply computes 
the difference. 

Lisp function 

divides its first (fixnum) argument successively by each of 
Its succeeding arguments. Answer is a whole number 
(fixnum). With two arguments, it is a simple integer 
quotient. 



< Lisp predicate 

of two arguments, fixnums. 
than second. 

=s Lisp predicate 

of two arguments, fixnums. 
same fixnum. 



Returns truth if first is less 



Returns truth if they are the 



> Lisp predicate 

of two arguments, fixnums. Returns truth if the first is 
greater than the second. 

add-error-code Emaes function 

of two arguments, error-code and error-string, adds an entry 
to the Emacs Error Table. 



aim-mode-hook Emacs global variable 

if bound to non-nil, its binding is assumed to be a symbol 
that can be called as a function as the last action of Emacs 
upon entering ALM mode in a buffer. Used to customize key 
bindings, etc. 

alphalessp Lisp predicate 

of two arguments, can be symbols or strings. Returns truth 
if the printname (or string value) of the first collates 
alphabetically in the ASCII collating sequence before the 
second. 

and Lisp special form 

evaluates all of its subforms in order until one of them 
evaluates to nil, or they are all evaluated. The value 
returned by the last one evaluated is returned. 

append Lisp function 

takes any number of lists as arguments, including empty 
lists. Returns a list with all the elements of the lists 
provided as elements, in order. 

apply-catenate Emacs function 

takes a list of any number of strings or symbols, and 

returns a string that is the catenation of all their string 

values or printnames. 
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ascii Lisp function 

returns a single-character symbol whose printname is the 
character whose ASCII numeric value was given as an 
argument. 

assert-minor-mode Emacs function 

of one argument, asserts that this minor mode (expected to 
be a symbol) has been turned on. It appears in the mode 
line in the current buffer. 

at Emacs predicate 

of one argument, a single-character string or symbol. 
Returns truth if the character to the right of point in the 
current buffer is this character. 

at-beginning-of-buf f er Emacs predicate 

returns truth if the current point in the current buffer is 
at the beginning of the buffer. 

at-end-of-buf f er Emacs predicate 

returns truth if the current point in the current buffer is 
at the end of the buffer. 

at-white-char Emacs predicate ^ 

returns truth if the character to the right of the current 
point in the current buffer is a whitespace character. 

back-at Emacs predicate 

of one argument, a single-character string or symbol, 
returns truth if the character to the LEFT of point in the 
current buffer is this character. 

base Lisp global variable 

normally 8, the binding of the variable controls the numeric 
base in which numbers are converted to their printed 
representation . 

bolp Emacs predicate 

returns truth if the current point in the current buffer is 
at the beginning of a line, 

buffer-creation-hook Emacs global variable 

if bound to non-nil, its binding is assumed to be a symbol 
that can be called as a function when a buffer is created^ 

buffer-destruction-hook Emacs global variable 

if bound to non-nil, its binding is assumed to be a symbol 
that can be called as a function when a buffer is destroyed. 

buffer-entrance-hook Emacs global variable 

if bound to non-nil, its binding is assumed to be a symbol 

that can be called as a function when a new buffer is 
selected. 
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I buffer-exit-hook Emacs global variable 

I if bound to non-nil, its binding is assumed to be a symbol 

I that can be called as a function when a buffer is left. 

buffer-kill Emacs function 

of one argument, the symbol representing a buffer. Destroys 
that buffer. 

buffer-minor-modes Emacs per-buffer variable 

the list of symbols that have been asserted and not negated 
as the current minor modes in the current buffer ► 

buf f er-modif ied-flag Emacs per-buffer variable 

value is non-nil if the current buffer has been modified 
since last read in or written out. Do not set this flag by 
yourself; let Emacs manage it. 

buf f er-on-display-in-window Emacs predicate 

.as a predicate, returns truth if the buffer whose symbol is 
provided as an argument is currently on display in any 
window. 

buf f er-on-display-in-window Emacs function 

as a function, returns the window number in which the buffer 
provided is on display (or nil if none). 

car Lisp function 

returns the "car" of the argument, which is expected to be a 
cons. Note that for conses which are parts of lists, car 
may be viewed as returning the first element of the list. 

catenate Lisp function 

given any number of strings or symbols as arguments, returns 
a string that is the catenation of their string-values or 
printnames. 

cdr Lisp function 

returns the "cdr" of the argument, which is expected to be a 
cons. Note that for conses that are parts of lists, cdr may 
be viewed as returning a list of all the elements beyond the 
first element. 

charscan-table Emacs function 

takes a character-string argument, and creates a charscan 
table that can be used to search a string for those 
characters. 

charset-member Emacs function 

the first argument is a single character string, r symbol, 
or fixnum that is the ASCII value of a charater. and the 
second argument is a charscan table. Returns truth if the 
character is a member of that charscan table. 
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close-line-hook Emacs global variable | 
if bound to non-nil, its binding is assumed to be a symbol | 
that can be called as a function when the user moves to | 
another line. | 

command-quit Emacs function 

aborts the execution of the current extension function, 
beeping, and returning to the Emacs character-listening 
loop. 

comment-column Emacs per-buffer variable 

the zero-based comment column in the current buffer. 

comment-prefix Emacs per-buffer variable 

the string to be inserted at the start of comments in this 
buffer, and searched for to find the start of already 
existent comments. 

comout-get-output Emacs function 

catenates all of its arguments into a Multics command line, 
and replaces the contents of the current buffer by the 
Multics output produced by executing that Multics command 
line. 

cond Emacs special form 

performs successive tests of conditions and conditionally 
executes forms. Specifically, evaluates the first subform 
of all of its own subforms, until one returns non-nil, and 
executes all the remaining subforms of that subform (of 
cond^ . returnina the value of the last subform, of any kind= 
evaluated. See the writeup/examples. 

cons Lisp function 

constructs a new cons, whose car and cdr are the two 
arg\jments given. 

Ctol Lisp function 

obtains the numeric ASCII value of the character that is the 
printname (if a symbol, or value if a string) of its 
argioment. 

cur-hpos Emacs function 

the zero-based current horizontal position of point on the 
current line in the current buffer. Note that this is 
horizontal position on an infinite-width line-printer or 
printing terminal, not on the screen. Tabs count, 
backspaces count, etc. 

curchar Emacs function 

returns the single-character symbol whose -printname is the 
character to the right of point in the current buffer. 
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current-buffer Emacs per-buffer variable 

the symbol representing the current buffer, 

current-buff er-mode Emacs per-buffer variable 

the symbol representing the major mode in the current 
buffer^ 

DCTL-clear-rest-of-screen CTL function 

clear to the end of the screen from the cursor, 

DCTL-delete- chars CTL. function 

delete n (argument) characters at the cursor, shifting the 
rest of the line over to the left* 

DCTL-delete-lines CTL function 

delete n (argument) lines from the screen at the cursor, 
moving the rest of the lines on the screen up. 

DCTL-display-char-string CTL function 

print the character string supplied as an argument at the 
cursor, moving the cursor to the end, 

DCTL -epilogue CTL function 

take appropriate actions to "reset" the terminal from Emacs 
mode to normal Multics mode. 

DCTL-init CTL function 

set up the CTL to operate and then clear the screen. 

DCTL-insert-char-string CTL function 

insert the character-string argiiment at the cursor, pushing 
the rest of the line over to the right. 

DCTL-insert-lines CTL function 

open up n (argument) blank lines at the cursor pushing the 
rest of the lines down, the n lowest off the screen. 

DCTL- kill- line CTL function 

clear from the cursor to the end of the line. 

DCTL-position-cursor CTL function 

takes X, y as arguments. Move the cursor (if not already 
there) to that position; x and y are zero based. 

DCTL-prologue CTL function 

ready the CTL for Emacs usage as opposed to Multics normal 
mode • 

BCTL-^scroll-down-region CTL function 

scroll a region at the cursor down. 

DCTL-scroll-up-region CTL function 

scroll a region at the cursor up. 
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debug-e Emacs function 

sets error traps in Emacs so that extension code bugs 
breakpoint in Lisp. 

decimal-rep Emacs function 

converts its (numeric) argument to a string that is its 
decimal representation. 

defcom Emacs special form 
defines a command. 

defprop Lisp special form 

puts a property on a symbol. Like putprop, but is a special 
form and does not evaluate any of its arguments. 

defun Lisp special form 
defines a function. 

defvar Emacs special form 

declares a special variable (first argument, not evaluated) 
and assigns a value if the variable has not been set when 
the program is loaded (second argument, evaluated). 

delete-white-sides Emacs function 

removes all whitespace characters on either side of point in 
the current buffer. 

delete-window Emacs function 

destroys the window whose window number is .given. 

der-wahrer-mark Emacs per-buffer variable 

"the true mark," i.e., the user-visible C^Q) mark in the 
current buffer. 

destroy-buf f er-contents Emacs function 

destroys the contents of the current buffer. 

dispatch-on-current-char Emacs special form 

executes forms conditionally based upon the value of the 
character to the right of point in the current buffer. 

dispatch-on-lef thand-char Emacs special form 

executes forms conditionally based upon the value of the 
character to the right of point in the current buffer. 

display-as-printout Emacs special form 

displays as local display all of the text placed in the 
current buffer (which will be created by this form) by the 
forms contained in it. 

display-buff er-as-printout Emacs function 

displays the current buffer as local display. 
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display-com-error Emacs function 

takes a Multics error code argument and strings that are 
catenated to produce an error message in the minibuffer 
(including the converted Multics error code), aborts the 
current extension code execution, and beeps. 

display-com-error-noabort Emacs function 

like display~com-error , but does not abort. 

display-error Emacs function 

catenates its string arguments, to produce an error message 
in the minibuffer,. aborts the current extension code 
execution r and beeps.. 

display-error-noabort Emacs function 

like display-error, but does not abort. 

display-error-remark Emacs function 

like display-error-noabort, but this output is suppressed 
during keyboard macro execution. 

do Lisp special form- 
complex native Lisp form for iterated execution. 

do-forever Emacs special form 

executes all of the forms contained within it until they 
return or abort of their own accord. 

do-times Emacs special form 

first form is evaluated to obtain a number; the rest of the 
forms are executed that many times. 

dont-notice-modif ied-buf f er Emacs function 

argument is a buf f er-symbol» If called, that buffer's being 

modified does not prevent the user from exiting Emacs 
without being queried. 

e_cline_ Emacs function 

executes a Multics command line (the supplied string) 
without any arrangements for I/O, etc. 

empty-buff er-p Emacs predicate 

returns truth if the buffer-symbol argument represents an 
empty buffer. 

end-local-displays Emacs function 

indicates that a local display has produced all it is going 
to, and the next charater typed by the user should erase the 

local display. 

env-dir Emacs global variable 

the directory in which the Emacs subsystem is located. 
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eolp Emacs predicate 

returns truth if the current point in the current buffer is 
at the end of a line. 

eq Lisp predicate 

returns truth if the same object is given as both arguments. 

error-table Emacs function 

of two arguments, segment and offset, gets a standard 
Multics error code. 

error_table_ Emacs function 

produces a Multics error code given an error table entry 
point name as a string or symbol. 

ESC Emacs global variable 

a single-character symbol whose name is the ESC character. 

establish-local-var Emacs function 

declares a buffer local variable and establishes a value. 

eval Lisp function 

evaluates a Lisp form. 

explode Lisp function 

creates a list of characters (single-character symbols) that 
is the standard Lisp printed representation of its argument. 

explodec Lisp function 

like explode, but does not escape Lisp special characters or 
quote strings. 

fill-mode-delimiters Emacs global variable . 

the list of characters that cause fill mode to fill^ 

f ind-buf f er-in-window Emacs function 

takes a buffer-symbol argument, and either selects a window 
containing that buffer, or first puts it somewhere other 
than the current window (on an LRU basis) and then selects 
that window. 

f ind-f ile-subr Emacs function 

takes an argument like those acceptable to '^X^F, and does as 
^Z^F does (reads file or files, selects buffers, etc.). 

firstlinep Emacs predicate 

returns truth if the current point is on the first line of 
the current buffer. 

fixp Lisp predicate 

returns truth if its argument is a fixnum (or bignum) . 
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format-to-col Emacs function 

puts whitespace in the current line at the current point, 
putting in at least one space. The argument is the column 
(zero-based) to format out to. 

f ortran-mode-hook Emacs global variable 

if bound to non-nil, its binding is assumed to be a symbol 
that can be called as a function as the last action of Emacs 
upon entering FORTRAN mode in a buffer. Used to customize 
key bindings, etc. 

forward-search Emacs function 

takes a string- (or symbol) argument. Searches foward (as 
does '^S) in the current buffer, returning truth if the 
search succeeds (and moving point) or nil if not. 

fpathname Emacs per-buffer variable 

pathname (or nil if. none) of file in current buffer. 

full-redisplay Emacs function 

clears the screen and redisplays all windows. 

funcall Lisp function 

calls a function (the first argument) upon all the rest of 
its arguments. Needed only when the identity of the 
function to be called is not known, i.e.., was obtained from 
the value of a variable. 



get Lisp special form 

first argument is a symbol, second a property. Obtains that 
property of that symbol, or nil if it hasn't one. 

get-char Emacs function 

returns (as a fixnum ASCII value) a single character read 
from the keyboard (or keyboard macro). Does not echo or 
prompt in any way. 

get-search-string Emacs function 

takes a prompt string. Gets a search string from the user 
(for use in writing search requests), and does defaulting 
and setting of defaults. 



go Lisp special form 

transfers to a PROG label. 



go-to-hpos Emacs function 

moves the current point to the character that would be at 
that (argument) _ horizontal position (see cur-hpos for a 
definition of horizontal position). 

go-to-mark Emacs function 

argument is a mark that must be in the current buffer. 
Moves point to that mark. 
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go-to-or-create-buf f er Emacs function 

argument is a buffer symbol. Goes to that buffer, creating 
it if it does not exist. If it did exist, point will be 
where it last was in that buffer, 

ibase Lisp global variable 

base (normally 8) for converting numbers typed into Lisp. 

if Emacs special form 

special form for conditional execution. Evaluates its first 
form. If non-nil, evaluates all following forms up to 
"else" or end of the "if"; otherwise, evaluates all forms 
after the "else" (if any). 

if -at Emacs special form 

first argument is a character symbol or string. Evaluates 
all the rest of its forms if the current character at the 
right of the point in the current buffer is this character. 

if-back-at Emacs special form 

same as if -at, but for the character to. the left of the 
point . 

init-local-displays Emacs function 

sets up for local display output. 

insert-string Emacs function 

of one argument, a string (or symbol) of any length. 
Inserts those characters to the left of the current point 
(thus moving it) in the current buffer. 

ItoC Lisp function 

creates a single-character string from the ASCII value given 
as an argument* 

killsave-str ing Emacs function 

pushes its string (or symbol) argument onto the kill ring. 
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kill-pop Emacs function 

returns the first item on the kill ring and rotates the kill 
ring. 



kill-ring-top Emacs function 

returns the first item on the kill ring. 



lastlinep Emacs predicate 

returns truth if the current point is on the last line of 
the current buffer. If there is a newline in the file, this 
means the line (which may be empty) immediately after the 
last newline. 



last-minibuf f er-response Emacs per-buffer variable 

The last response given in the minibuffer. When ESC X opt 
remember-empty- response is set off, last-minibuf f er-response 
is not set to blank when a blank response is given. 
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Idebug-mode-hook Emacs global variable 

if bound to non-nil, its binding is assumed to be a symbol 
that can be called as a function as the last action of Emacs 
upon entering LDEBUG mode in a buffer. Used to customize 
key bindings, etc. 

lef thand-char Emacs function 

returns a single character symbol whose printname is the 
character to the left of point in the current buffer. 

let ^ Lisp special form 

'establishes variables and their bindings for a computation. 

line-is-blank Emacs predicate 

returns truth if the current line of the current buffer (the 
one on which point is) has no characters, or only whitespace 
characters. 

lisp-mode-hook Emacs global variable 

if bound to non-niL, its binding is assumed to be a symbol 
that can be called as a function as the last action of Emacs 
upon entering LISP mode in a buffer. Used to customize key 
bindings, etc. 

list Lisp function 

returns a list whose elements are list's arguments. 

list* Lisp function 

returns a list-like chain of conses, whose first n-1 
elements are list*'s first n-1 arguments, but the cdr of 
whose last cons is list*'s nth and last argument. 

local-display-current-line Emacs function 

displays the current line of the current buffer as local 
display (a local display must already have been 
established) . 

local-display-generator Emacs function 

takes a string (which must end in a newline) and displays it 
as local display. 

local-display-generator-nnl Emacs function 

like local-display-generator, but adds the newline for you. 

looking-at Emacs predicate 

returns truth if the string given as an argument (which must 
not contain a newline) appears immediately to the right of 
the current point in the current buffer. 
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mail -mode-hook Emacs global variable 

if bound to non-nil, its binding is assumed to be a symbol 
that can be called as a function as the last action of Emacs 
upon entering MAIL mode in a buffer. Used to customize key 
bindings, etc, 

maknam Lisp function 

makes a new symbol, not interned, whose name is formed from 
ttte supplied list of characters (symbols or fixnums, the 
latter interpreted as specifying ASCII values). 

mapc Lisp function 

an" iterator; first argument specifies a function. Second 
through last arguments are lists. The function is marched 
through the elements of the lists, in parallel. 

mark-at-current-point-p Emacs predicate 

ta:;kes a mark as argument. Returns truth if that mark 
specifies the place in the current buffer where the current 
point is. 

mark-on-current-line-p Emacs predicate 

ta^es a mark as argument. Returns truth if that mark 
spi^cif ies a point on the same line of the current buffer 
where the current point is. 

mark-reached Emacs predicate 

takes a mark as argument. Returns truth if current point 
ha^ passed this mark in the current buffer. There are 
restrictions on this (see the writeup). 

mark-same-line-p Emacs predicate 

takes two marks as arguments. Returns truth if they 
re'^resent points on the same line. 

memg Ldsp predicate 

returns truth if its first argument is a member of the list 
that is its second argument. 

minibu^er-clear-all Emacs function 

no- arguments , completely clears the minibuffer.. 

<■ 

minibuf fer-response Emacs function 

takes two arguments; the first is a prompt string, and the 
second is either NL or ESC - prompts the user with that 
string in the minibuffer, requiring that termination 
character. Returns the string result of the user's typing. 

minibuf f er-clear Emacs function 

clears the current line of the minibuffer. 
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minibuf f er-print Emacs function 

takes any number of arguments, expected to be strings or 
symbols, catenates and prints them in the minibuf fer. 

minibuf fer-print-noclear Emacs function 

like minibuf f er-print , but appends these strings to the last 
active line of the minibuf fer, 

nconc Lisp function 

like append,, but destructively rethreads its arguments to 
produce itsr result. Be careful to utilize the result value 
of nconc 

negate-minor-mode Einacs function 

asserts that a minor mode (specified by its symbol. argument ) 
is no longer in effect in the current buffer. The mode is 
removed from the mode line at the next redisplay. 

next-line Emacs function 

places the current point in the current buffer at the 
beginning of the next line in that buffer. 

nil Lisp global variable 

its; value is itself, nil, which is both the indicator of 
falsity and the emtpy list. 

NL Emacs global variable 

a symbol whose printname is an ASCII newline character, 

not Lisp predicate 

returns truth if its argument is the symbol "nil". 

nreverse Lisp function 

like reverse, but destructively rethreads the list it is 
given. Be careful to use the return value of nreverse, 

null Lisp predicate 

returns truth if its argument is the symbol "nil". 

null-stringp Emacs predicate 

returns truth if its argument is a null string or the symbol 
whose printname has no characters. 

nuwindows Emacs per-buffer variable 

the number of windows on the screen (not including 
minibuf fer or mode line). 

or Lisp special form 

evaluates all of its subforms sequentially until one is 
evaluated to anything but nil, or its last subform is 
evaluated, whichever comes first. Returns the last form it 
evaluates. 
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pll-mode-hook Emacs global variable 

if bound to non-nil, its binding is assumed to be a symbol 
that can be called as a function as the last action of Emacs 
upon entering PL/I mode in a buffer. Used to customize key 
bindings, etc, 

point-mark-to-string Emacs function 

returns as a string a copy of all text between the mark 
given as an argument and the current point in the current 
buffer. 

point>markp Emacs predicate 

takes a mark as an argument. Returns truth if the current 
point is further on in the buffer than the place represented 
by that mark. 

prev-line Emacs function 

moves the point to the beginning of the previous line of the 
current buffer. 

previous-buffer Emacs per-buffer variable 

the symbol of the previous buffer Emacs was in. 

print Emacs function 

prints out (to normal Multics output) the printed 
representation of its argument. 

process-char Emacs function 

called on a fixnum that is an ASCII character 

reoresentat ion J interprets that character (including reading 
more, if necessary) as an Emacs request. 

process-dir Emacs global variable 

the pathname (a character string) of the process directory 
of the process using Emacs. 

prog Lisp special form 

sequentially evaluates forms within it, allowing use of 
local variables and labels. Returns nil, or the value 
supplied to "return". 

progl Lisp special form 

evaluates sequentially all of the forms within it, returning 
the value of the first. 

prog2 Lisp special form 

evaluates sequentially all of the forms within it, returning 
the value of the second. 

progn Lisp special form 

evaluates sequentially all of the forms within it, returning 
the value of the last. 
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protect Lisp special form 

evaluates and returns the value of its first subform. The 
remaining forms are then evaluated according to the success 
or failure of the first form's evaluation, as specified by 
special clauses. 

putprop Lisp function 

puts its second argument as the property specified by its 
third argument on its first argument, which must be a 
symbol. 

read~f rom-string- Lisp function: 

performs a Lisp "read" operation on the contents of the 
string supplied, creating (or finding) and returning the 
Lisp object whose printed representation was specified by 
the string. 

read-in-file Emacs function 

takes a pathname argument; reads it into the current buffer. 

read-only-flag Emacs per-buffer variable 

when set (when buf f er-modif ied-f lag has not yet been set) 
prevents a user from modifying the buffer. For 
pseudo-editable displays (like OIRED) . 

redisplay Emacs function 

updates the screen to reflect all changes in buffers on 
display. 

redisplay-current-window-relative Emacs function 

takes a line number on which to position the current line of 
the current buffer in the current window, where it is 
assumed to be on display. What ^L with an argument does. 

regexp-search Emacs function 

like forward-search but does a "regular expression" search 
(as ESC / does) . 

register-local-variable Emacs function 
sets up a per-buffer variable. 

register-option Emacs function 

sets up an Emacs user option. First argument is a symbol 
(that is the option name and variable) and second argument 
is a default value. 

release-mark Emacs function 

takes a mark as an argument. Invalidates that mark, and 
frees Emacs from having to manage it any m.ore* 
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report-error Emacs function 

of two arguments, error-code and error-information, aborts 
the current computation and prints an error. 

report-error-noabort Emacs function 

of two arguments, error-code and error-information, prints 
an error without aborting. 

return Lisp function 

returns a value from a do, prog, do-times, or do-forever. 

reverse Lisp function 

takes a list as an argument, returns a list with the same 
elements but in opposite order. 

reverse-regexp-search Emacs function 

like reverse-search but does a "regular expression" search. 

reverse-search Emacs function 

searches backward for its (string or symbol) argument from 
the current point in the current buffer, as does '^R (which 
uses it). Returns truth and moves point to before this 
string if the search succeeds. 

ring-tty-bell Emacs function 
beeps the tty bell. 

rmail-mode-hook Emacs global variable 

if bound to non-nil, its binding is assumed to be a symbol 
that can be called as a function as the last action of Emacs 
upon entering RMAIL mode in a buffer. Used to customize key 
bindings, etc. 

rotate-kill-ring Emacs function 
rotates the kill ring. 

rplaca Lisp function 

first argument is a cons, the second is anything else. The 
second argument is made to be the car of the cons, which is 
returned as a value. 

rplacd Lisp function 

first argument is a cons, the second is anything else. The 
second argument is m.ade to be the cdr of the cons, which is 
returned as a value. 
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Rprinc Emacs function 

to be used only by CTLS; "sends" a character string in raw 
mode to the terminal. This function does not work unless 
invoked by the CTL at redisplay time. 

Rtyo Emacs function 

to be used only by CTLS; "sends" a single character, 
specified by numeric ASCII value, in raw mode to the 
terminal. This function does not work unless invoked by the 
CTL at redisplay time. 
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samepnamep Lisp predicate 

returns truth if both arguments are symbols of the same 
printname, or strings of the same character-string value, 

save~excursion Emacs special form 

remembers where the point was in the current buffer when it 
was invoked, and restores it to there after evaluating the 
forms within. The value of save-excursion is the value of 
its: last evaluation.. 

save-excursion-buf f er Emacs special form 

remembers what buffer it was in when invoked, and restores 
Emacs to be in that buffer when exited after evaluating the 
forms vrithin» 

save-excursion-on-error Emacs special form 

remembers where the point was in the current buffer when it 
was invoked, and restores it to there if an error occurs 
while evaluating the forms within. 

search-back-f irst-charset-line Emacs function 

takes a charscan table as an argument. Scans backward in 

a character in this charscan table. Returns truth and moves 
point if it succeeds. 

search-back-f irst-not-charset-line Emacs function 

takes a charscan table as an argument. Scans backward in 
the current line until the current point is to the right of 
a character not in this charscan table. Returns truth and 
moves point if it succeeds. 

search-charset-backward Emacs function 

takes a charscan table as an argument. Scans backward in 
the current buffer until the current point is to the right 
of a character in this charscan table. Returns truth and 
moves point if it succeeds. 

search-charset-f orward Emacs function 

takes -a charscan table as an argument. Scans forward in the 
current line until the current point is to the left of a 
character in this charscan table. Returns truth and moves 
point if it succeeds. 

search-failure-annunciator Emacs function 

indicates that a search has failed, beeps, and aborts. To 
be used by search requests. 

search-f or-f irst-charset-line Emacs function 

takes a charscan table as an argument. Scans forward in the 
current line until the current point is to the left of a 
character in this charscan table. Returns truth and moves 
point if it succeeds. 



B-26 



CJ52-01 



search-f or-f irst-not-charset-line Emacs function 

takes a charscan table as an argijinent. Scans forward in the 
current line until the current point is to the left of a 
character not in this charscan table. Returns truth and 
moves point if it succeeds. 

search-not-charset-backward Emacs function 

takes a charscan table as an argument. Scans backward in 
the current buffer until the current point is to the right 
of a character in this charscan table. Returns truth and 
moves point if it succeeds. 

search-not-charset-f orward Emacs function 

takes a charscan table as an argument. Scans forward in the 
current buffer until the current point is to the left of a 
character not in this charscan table. Returns truth and 
moves point if it succeeds. 

select-buffer-find-window Emacs function 

tries to put a buffer on the screen. See the section on 
window management. 

select-buffer-window Emacs function 

takes a buffer symbol and a line count as argument, and 
tries to get that buffer on the screen, putting it in the 
current window if it is not now on the screen. See the 
section on window management. 

select-window Emacs function 

takes a window number as argument. Moves the cursor to 
(selects) that window. 

selected-window Emacs per-buffer variable 

the window number of the window in which the cursor 
currently appears. 

set-buffer-self-destruct Emacs function 

takes a buffer symbol as argument. After this function is 
used, that buffer will be destroyed the first time it is 
exited. 

set-key Emacs function 

assigns key bindings in the current buffer. Takes two | 
arguments, the key name via a string or symbol, and the j 
function name via a symbol. The key name can be anything j 
like the names in the documentation, e.g., ^X, ^x, ESC ESC, j 
^Xq, control-p, c-p, meta-f, ESC '^f, etc. See Section 15 of | 
the Emacs Text Editor Users ' Guide for a full description of j 
acceptable key names. | 
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set-mark Emacs function 

creates a mark at the point where the current point is in 
the current buffer, and maintains it thereafter. Be sure to 
release-mark such marks, or use with-mark. 



set-permanent-key, set perm-key Emacs function 

sets a key to invoke a function in all buffers. Like 
set-key, takes two arguments, the keyname via a string or 
symbol, and the function name, via a symbol. See Section 15 
of. the Emacs Text Editor Users ' Guide for a full description 
of acceptable key names.. 

setq Lisp special form 

assigns a value to a variable. 

skip-back-to-whitespace Emacs function 

moves current point backward in current buffer 
whitespace character (or the beginning of the 
whichever comes first) is to the left of it. 

skip-back-whitespace Emacs function 

moves current point, backward in current buffer until a 
non-whitespace character (or the beginning of the buffer, 
whichever comes first) is to the left of it- 

skip-back-whitespace-in-line Emacs function 

moves current point backward in current buffer until a 
non-whitespace character (or the beginning of the line, 
whichever comes first) is to the left of it. 

skip-over-whitespace Emacs function 

moves current point in current buffer forward over all 
whitespace characters until the first non-whitespace 
character. 



until a 
buffer, 



skip-over-whitespace-in-line Emacs function 

moves current point in current buffer forward over all 
whitespace until the end of the line. 



skip-to-whitespace Emacs function 

moves current point in current buffer over all 
non-whitespace characters until the next whitespace 
character , 



stop-doing Emacs special form 

causes do/do-forever to exit, returning nil. 

stringp Lisp predicate . 

returns truth if its argument is a string. 

symbolp Lisp predicate 

returns truth if its argument is a symbol. 
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t Lisp global variable 

its value is itself, which represents canonical truth, 

tab-equivalent Emacs per-buffer variable 

sets how many spaces a tab is "worth" (normally ten) in the 
current buffer. 

text-mode-hook Emacs global variable 

if bound to non-nil, its binding is assumed to be a symbol 
that can be called as a function as the last action of Emacs 
upon entering TEXT mode in a buffer. Used to customize key 
bindings, etc. 

trace Lisp special form 

causes Lisp functions to be traced. 

unwind-protect Lisp special form 

evaluates and returns the value of its first subform. The 
remaining subforms are evaluated after the first form's 
evaluation is finished, or when that first evaluation is 
aborted. This is how you set up a "cleanup handler". 

view-region-as-lines Emacs function 

displays the region in the current buffer as local display. 

whitespace-to-hpos Emacs function 

places whitespace, in optimal tabs and spaces, at the 
current point in the current buffer, moving it until the 
specified (as argument) horizontal position has been 
reached. 

window-adjust-lower Emacs function 

adjusts the lower boundary line of a window. First argument 
is window number, second is how much to move it, signed, 

window-ad just-upper Emacs function 

adjusts the upper boundary line of a window. First argument 
is window number, second is how much to move it, signed. 

window-info Emacs function 

returns a list of information about the window whose window 
number is given as an argument. 

wipe-point-rmark Emacs function 

takes a mark as argument. Deletes all text in the current 
buffer between the current point and this mark, saving it on 
the kill ring unless without-saving is being used. 

with-mark Emacs special form 

creates a mark in the current buffer at the place where the 
current point is when with-mark was invoked. The variable 
whose name appears first in the with-mark form is bound to 
this mark; with-mark frees this mark automatically. 
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without-modifying Emacs special form 

evaluates the forms within it, but the buffer is not marked 
as modified even though these forms may modify it. 

without-saving Emacs special form 

evaluates the forms contained within it, but the automatic 
saving of killed text on the kill ring is suppressed. 

write-out-f ile Emacs function 

takes a pathname argument. Writes the current buffer out to 
that filev 

yesp Emacs predicate 

takes a. string argument. Asks the user that question in the 
minibuffer, and returns truth in response to a "yes" answer, 
rejecting all answers but "yes" or "no". 
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INDEX 



MI SCELLANEOUS 



Scarguments defcom keyword 

3-63, 3-64, 3-66, 3-68, 
3-69 

^cleanup defcom keyword 3-66, 
3-68, 3-69 

fitcompletions defcom keyword 
3-66, 3-67 

Stdocumentation defcom keyword 
3-66 

^epilogue defcom keyword 3-65, 
3-68, 3-69 

fitinverse defcom keyword 3-67, 
3-68 

&negative-f unction 3-66 

tnegative-f unction defcom 
keyword 3-68 

fiinumeric-argument defcom 

keyword 3-61, 3-62, 3-66, 
3-68 

&numeric-f unction defcom 
keyword 3-62 

^prologue 3-66 



fitprologue defcom keyword 3-65, 
3-68 

&undo defcom keyword 3-67 
(*rset t) mode 3-48 
*nopoint global variable 2-19 
+ function 2-2 
-function 2-1 

/{Lisp escape character) 2-11 
//function 2—11 
< predicate 2-5 
s= predicate 2-5 
> predicate 2-5 

A 

add-error-code function 3-60 

addition 

+funct.ion 2-1 

alphalessp predicate 2-6 

and special form 2-11 

append function 2-16 
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apply-catenate function 2-18, 
3-31 

ascii function 3-43 

assert-minor-mode function 
3-39 

at. predicate 3-12 

at.-beginning-of -buffer 
predicate- 3=11 

at-end-of-buf f er predicate 
3-11 

at-white-char predicate. 3-11 

attribute 

see symbol, property 

autophanic request 3-52 



5 



faack-at predicate 3-12 

backquote 2-18, A-1 

base global variable 2-19 

binding 2-3, 2-16 

bolp predicate 3-11 

breakpoint 4-4 

buffer 

dont-not ice-modi fied-buffer 

3-29 
Idebug 4-1 
nontemporary 3-28 
symbol 3-27, 3-52 
temporary 3-27 

buffer-creating 3-3, 3-26 

buffer-kill function 3-29 



buffer-minor-modes variable 
3-23, 3-39 

buf f er-modif ied-f lag variable 
3-22 

buf fer-on-di splay- in-window 
function 3-56 
predicate 3-56 

builtin function 
J- 2—2 
list "2-14 
print 2-2 
rplaca 2-15 
rplacd 2-15 



C 



car 2-13 

catenate function 3-31 
cdr 2-13 

character object 3-40 

character/number conversion 
3-43 

characters 

searching for 3-33 

charscan-table function 3-33 

charset-member predicate 3-34 

cleanup handler 
protect 3-10 

cleanup-handler 

unwind-protect 3-9 

command executing 
Multics 3-58 

command-quit function 3-18 

comment 2-1 
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comment -column variable 3-22 

comment-prefix variable 3-22 

comout-get-output 3-59 

compilation 3-48, 3-49 

compiling an extension 3-48 

cond special form 5-10 

cons 2-13 

construct 
see cons 

control argument 
-line_length 5-3 
-line__speed 5-3 
-page_length 5-3 
-query 5-2 
-terminal^type 5-2 

conversion 

character/number 3-43 
number/character 3-43 

CTL 5-1 

CTL functions 
see DCTL • 

Ctol function 3-43 

cur-hpos function 3-6 

curchar function 3-40 

current-buffer variable 3-29 

current-buffer-mode variable 
3-22, 3-38 

cursor position 
cur-hpos 3-6 
go-to-hpos 3-6 
predicates reflecting 3-11 



D 



DCTL-clear-rest-of -screen 
function 5-6 

DCTL-delete-chars function 
5-8 



DCTL-delete-lines function 
5-7 

DCTL-di splay-char-string 
function 5-5 

DCTL-epilogue function 5-7 

DCTL-init function 5-2, 5-4, 
5-6 

DCTL- insert-char-string 
function 5-7 

DCTL-insert-lines functions 
5-7 

DCITi- kill -line function 5-6 

DCTL-position-cursor function 
5-5 

DCTL-prologue function 5-7 

DCTL-scroll-down-region 
function 5-9 

DCTL-scroll-up-region function 
5-8 

debug-e function 3-48 

debugging 3-48, 4-1 

decimal-rep function 2-18, 
3-15 

declarations 3-49 

default specification 3-63 

defcom 3-61, 3-62, 3-63, 3-64, 
3-65, 3-66, 3-67, 3-68 
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defcom (cont) 
keywords 3-61 

Siarguments 3-63, 3-64, 

3-66, 3-68, 3-69 
Stcleanup 3-66, 3-68, 3-69 
Stcompletions 3-66, 3-67 
Stdocumentation 3-66 
Stepilogue 3-65, 3-68, 
3-69 

^inverse 3-67, 3-68 
&negative-f unction 3-66, 
3-68- 

&numeric-argument 3-61, 

3-62, 3-66, 3-68 
Stnumeric- function 3-62 
Siprologue 3-65, 3-68 
Stundo 3-67 

defprop function 3-37 

defprop special form 3-37, 
3-50- 

defun special form 2—1, 2—7 

defvar special form 3-19 

delete-white-sides function 
3-13 

delete-window function 3-56 

deleting 
line 3-3 
region 3-3 

der-wahrer-mark variable 3-22 

destroy-buffer-c on tents 
function 3-29 

dispatch-on-current-char 
special form 3-42 

dispatch-on-lef thand-char 
special form 3-42 

display 3-25 

display-as-pr intout special 
form 3-26 



display-buff er-as-pr intout 
function 3-25 

display-com-error function 
3-17 

display-com-error-noabort 
function 3-17 

display-error function 3-16 

display-error-noabort function 
3-17 

display-error-remark function 
3-18 

division 

//function 2-11 

do special form 5-11 

do-forever special form 2-9 

do-times special form 3-5 

documenting requests 3-50 
Sidoc 3-66 

dont-not ice-modi fied-buffer 
function 3-29 

E 

element 2-13 

else keyword 2-7 

empty-buff er-p predicate 3-12, 
3-28 

end-local-displays function 
3-24 

entry value 4-3 

env-dir global variable 3-20 

eolp predicate 3-10 
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epilogue 3-65 

eq predicate 2-6, 3-40, 5-4 

error 3-8.1 

Emacs error system 3-60 

functions 3-60 
handling 4-1 
table 3-59 
trap entry 4-3 

error-table function 3-60 

error_table_ function 3-59 

ESC (Idebug) 4-4 

ESC G (Idebug) 4-2, 4-3 

ESC global variable 3-16 

ESC L (Idebug) 4-4 

ESC P (Idebug) 4-4 

ESC R (Idebug) 4-4 

ESC T (Idebug) 4-3 

ESC '^C(lisp) 3-49 

ESC '^S (Idebug) 4-5 

escape character (Lisp) 2-11 

establish-local-var function 
3-21 

evaluation 2-2 
conditional 2-7 
of functions calls 2-3 
of numbers 2-3 
of strings 2-3 

execution 

see evaluation 

explode function 2-18 

explodec function 3-27 



extension 

definition of 1-1 

e cline 3-58 



F 



reading/writing 3-3 

f ill-mode-delimeters variable 
3-39 

f ind-buf f er-in-window function 
3-52 

f ind-f ile-subr function 3-3 

firstlinep predicate 3-11 

fixp predicate 2-6 

form 2-2, 2-3, 2-4, 2-16 
not 2-11 
special 2-6 

and 2-11 

cond 5-10 

defprop 3-37, 3-50 

defun 2-7 

defvar 3-19 

dispatch-on-current-char 
3-42 

dispatch-on-lef thand-char 
3-42 

display-as-printout 3-26 

do 5-11 

do-forever 2-9 

do-times 3-5 

get 3-27 

go 2-10 

if 2-7 

if-at 3-41 

if-back-at 3-41 

let 2-9 

or 2-11 

prog 2-10 

progl 2-12 

progn 2-11 

protect 3-10 

putprop 3-27 
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form (cont) 
special 

save-excursion 3-7 
save-excurs ion-buffer 
3-29 

save-excursion-on-error 

3-7 
setq 2-8 
• unwind-protect 3-9 
with-mark 3-6 
without-modifying 3-8 
without- saving 3-5 
stop-doing 2-9 

format-to-col function 3-14 

forward-search function 3-3 

forward-search- in-line 
function 3-15 

fpathname variable 3-22 

f ull-redi s^la"^ function 3-4, 
3-32/3-33 

funcall function 3-38, 3-39 

function 2-1, 2-4 
add-error-code 3-60 
append 2-16 

apply-catenate 2-18, 3-31 
ascii 3-43 

assert-minor-mode 3-39 

buffer-kill 3-29 

buf fer-on-di splay- in-window 

3-56 
car 2-13 
catenate 3-31 
cdr 2-13 

charscan-table 3-33 
command-quit 3-18 
comout-get-output 3-59 
cons 2-13 
Ctol 3-43 
cur-hpos 3-6 
curchar 3-40 
DCTL-clear-rest-of -screen 
5-6- 

DCTL-dslets-chars 5-8 
DCTL-delete-lines 5-7 



function (cont) 

DCTL-di splay-char-string 
5-5 

DCTL-epilogue 5-7 
DCTL-init 5-4 

DCTL-insert-char-str ing 5-7 
DCTL-insert-lines 5-7 
DCTL- kill-line 5-6 
DCTL-position-cursor 5-5 
DCTL-prologue 5-7 
DCTL.-scroll-down-region 5-9 
DCTL-scroll-up- region 5-8 
decimal-rep 2-18, 3-15 
definition 2-1 
delete-whi te-sides 3-13 
delete-window 3-56 
destroy-buf f er-contents 
3-29 

display-buff er-as-printout 
3-25 

display-com-error 3-17 
display-com-error-noabort 
3-17 

display-error 3-16 
display-error-noabort 3-17 
display-error-remark 3-18 
dont-notice-modif ied-buf f er 
3-29 

Emacs requests 3-1 

exceptions 3-2 
end-local-displays 3-24 
error-table 3-60 
error_table_ 3-59 
establish-local-var 3-21 
explode 2-18 
explodec 3-27 
e cline__ 3-58 
fTnd-buf f er-in-window 3-52 
f ind-f ile-subr 3-3 
for CTLs 5-2 
format-to-col 3-14 
forward-search 3-3 
forward-search-in-line 3-15 
full-redisplay 3-4, 3-32, 
3-33 

funcall 3-38, 3-39 
get-char 3-43 
get-search-string 3-57 
go-to-hpos 3-6 

ao-to-or-create-buf f er 3-3, 
3-27 
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function (cont) 

init-local-displays 3-24 
insert-string 3-4 
ItoC 3-43 

kill=pop 3-8.1, B-5.1, 
B-19.1 

kill-ring-top 3-8.1, B-5.1, 

B-19.1 
killsave-string 3-8 
lef thand-char 3-41 
list 2-14 
list* 2-15 

local-display-current-line 
3-25 

local-display-generator 
3-24 

maknam 2-18, 3-27 
mapc 3-39 

minibuf f er-clear 3-17 
minibuf f er-clear-all 3-16 
minibuf fer-print 3-15 
minibuf fer-print-noclear 
3-17 

minibuf fer-response 3-16 
nconc 2-16 

negate-minor-mode 3-39 
next- line 3-3 
nreverse 2-16 
point-mark-to-string 3-3, 

3-14 
prev-line 3-3 
process-char 3-44 
read-f rom-string 2-19 
read-in-file 3-3 
redisplay 3-31 
redi splay-current-window 

-relative 3-4, 3-33 
regexp-search 3-3 
regexp-search-in-line 3-15 
register-local-variable 

3-20 

register-option 3-35 
release-mark 3-5 
report-error 3-60 
report-error-noabort 

function 3-60 
reverse 2-16 
reverse-regexp-search 

B-8, B-25 
reverse-search 3-3 
reverse-search-in-line 3-15 
ring-tty-bell 3-18 



function (cont) 

rotate-kill-ring 3-8,1, 

B-5.1, B-25 
Rprinc 5-4 
Rtyo 5-4 
search-back- first 

-charset-line 3-34 
search- back-first-not 
-charset-line 3-34 
search-charset-backward 
3-34 

search-charset-f orward 3-34 
search-failure-annunciator 
3-57 

search-f or-f irst 
-charset-line 3-34 

search-f or-f irst-not 
-charset-line 3-34 

search-not-char set-backward 
3-34 

search-not-charset- forward 
3-34 

select-buff er- find-window 
3-54 

select-buffer-window 3-53 
select-window 3-56 
set-buf f er-self -destruct 

3-28 
set-key 3-38 
set-mark 3-5 
skio-back-to-whi tespace 

3-13 

skip-back-whitespace 3-13 
skip-back-whitespace-in-line 
3-13 

skip-over-whitespace 3-13 
skip-over-whi tespace- in-line 
3-13 

skip-to-whitespace 3-13 
stringlength 5-5 
view-region-as-lines 3-25 
whitespace-to-hpos 3-14 
window-adjust-lower 3-56 
window-adjust-upper 3-56 
window-info 3-56 
wipe-point-mark 3-3, 3-5 
write-out-f ile 3-3 

function call 2-4 
syntax 2-3 
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G 

get special form 3-27 

get-char function 3-43 

get-search-string function 
3-57 

given-tty-type variable 5-4 

global variable 
nil 2-8 

see variable, global 
t 2-8 

go special form 2-10 

go-to-hpos function 3-6 
as predicate 3-6 

go-to-mark function 3-6 

go-to-or-creat-buf fer function 
3-3 

go-to-or-create-buf f er 3-26 

go-to-or-create-buf f er 

function 3-26, 3-27 

H 

heterophanic request 3-52 

hook 

mode 3-23 

I 

ibase global variable 2-19 

if special form 2-7 
syntax 2-7 

if-at special form 3-41 



if-back-at special form 3-41 

indicator 3-26 

init-local-displays function 
3-24 

insert-string function 3-4 
interned symbol 3-26 
ItoC function 3-43 

K 

keyword 
else 2-7 

kill-pop function 3-8,1, 
B-5.1, B-19.1 

B-5.1, B-19.1 

killsave-string function 3-8 

L 

label 2-10 

last-minibuf fer- response 
variable 3-16 

lastlinep predicate 3-11 

Idebug mode 

Idebug-di splay- where 
-editor-was 
ESC '^S 4-5 

Idebug-list-breaks 
ESC L 4-4 

Idebug- reset-break 
ESC R 4-4 
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Idebug-return-to-emacs 
-top-level 
ESC G 4-2 

Idebug- trace-stack 
ESC T 4-3 

left hand-chair function 3-41 

let special form 2-9 
syntax 2-10 

line-is-blank predicate 3-12 

Lisp debug mode 
see Idebug 

Lisp macro A-1 
see macro 

Lisp macros 3-49 

list 2-13 

list function 2-14, 2-15 

loading an extension 3*1, 
3-45 

local display 3-24 

local variable 

see variable, local 

local-display-current-line 
function 3-25 

local -display-generator 
function 3-24 

looking-at predicate 3-2, 
3-11 

looping 

see do-forever 2-9 



M 



macro 2-17 



macro character 
backguote A-1 
comma A-1 

major mode 
see mode 

maknam function 2-18 

maknem function 3-27 

mapc function 3-39 

mark 3-5 

go-to-mark 3-6 
predicates 3-11 
release-mark 3-5 
save-excursion 3-7 
set-mark 3-5 
temporary 3-5 
wipe-point-mark 3-3 
with-mark 3-6 

mark-at-current-point-p 
predicate 3-11 

mark-on-current-line-p 
predicate 3-12 

mark-reached predicate 3-11 

mark-same-line-p predicate 
3-12 

memg predicate 3-39 

minibuffer 3-15 

functions 3-16, 3-17 
yesp 3-12 

minibuf f er-clear function 
3-17 

minibuf fer-clear-all function 
3-16 

minibuf fer-print function 
3-15 

minibuf fer-pr in t-noclear 
function 3-17 
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minibuf f er-response function 
3-16 

minor mode 
see mode 

mode 

hook 3-23 
Idebug 4-1 
major 3-37 
minor 3-3.7^ a-39 

mode-hoolc 3-39 

multiple windows, 
see windows 

multiplication 
♦function 2-1 



N 



names 

choosing 3-36 

nconc function 2-16 

negate-minor-mode function 
3-39 

negative function 3-66 

negative-function defcom 
' keyword 3-66 

next-line function 3-3 

nil global variable 2-8 

nil symbol 3-4 

NL global variable 3-16 

not form 2-11 

nreverse function 2-16 

null-stringp predicate 3-12 



numarg global variable 3-4 

number/character conversion 
3-43 

numeric arguments 3-4 
do-times 3-5 

nuwindows variable 3-55 

0 

obarray 2-12, 3-26 
object 2-6, 2-18 
object, program 3-48 
operand 2-10 
option 3-35 
or special form 2-11 
ospeed variable 5-3 

P 

parentheses 2-3 

per-buffer variable 
see variable, local 

point-mark-to-string function 
3-3, 3-14 

point>markp predicate 3-11 

pop-up window mode 3-53 

predicate 2-5 
< 2-5 
^ 2-5 
> 2-5 

alphalessp 2-6 

-»+. "3-1 o 
aw ^ .x, *. 

at-beginning-of-buf f er 3-11 
at-end-of -buf f er 3-11 
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predicate (cont) 

at-white-char 3-11 
back-at 3-12 
bolp 3-11 

buffer-on-di splay- in-window 
3-56 

char set -member 3-34 
empty-buff er-p 3-12, 3-28 
eolp 3-10 
eq 2-6, 3-40, 5-4 
firstlinep 3-11 
fixp 2-6 
go-to-hpos 3-6 
lastlinep 3-11 
line-is-blank 3-12 
looking-at 3-2, 3-11 
mark-at-current-point-p 
3-11 

mark-on-current-line-p 3-12 
mark-reached 3-11 
mark-same-line-p 3-12 
memq 3-39 
null 2-6 

null-stringp 3-12 
point>markp 3-11 
samepnamep 2-6 
stringp 2-6 
symbolp 2-6 
yesp 3-12 

prev-line function 3-3 

previous-buffer variable 3-29 

print function 2-2 

printname 2-12 

problem 

monitoring 3-21 

proces-dir global variable 
3-20 

process^char function 3-44 
prog special form 2-10 
progl special form 2-12 
progn special form 2-11 



prologue 3-65 

prompting 

Stprompt 3-64 

minibuf f er-response 3-16 

property 2-16, 3-26 
documentation 3-50 

protect special form 3-10 

putprop special form 3-27 



R 



read-f rom-string function 
2-19 

read-in-f ile function 3-3 

read-only-flag variable 3-22 

redisplay 3-31, 3-33 

redisplay function 3-31 

redi splay-current-window 

-relative function 3-4, 

regexp-search function 3-3 

regexp-search- in-1 ine f unct i on 
3-15 

region 

copying 3-3 
deleting 3-3 

region scrolling 5-8 

region-scroll-availablep 
variable 5-8 

register-local-variable 
function 3-20 

register-option function 3-35 
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registering a variable 
functions 3-20 

release-mark function 3-5 

report-error function 3-60 

return function 2-9 

returned value 2-1 

reverse-regexp-search function 
B-8, B-25 

reverse function 2-16 

reverse-search function 3-3 

reverse-search- in-line 
function 3-15 

ring-tty-bell function 3-18 

rotate-kill-ring function 
3-8.1, B-5.1, B-25 

rplaca function 2-15 

rplacd function 2-15 

Rprinc function 5-4 

Rtyo function 5-4 



samepnamep predicate 2-6 

save-excursion special form 
3-7 

save-excursion-buf f er special 
form 3-29 

save-excursion-on-error 
special form 3-7 

scanning character 3-33 

screen 3-33 



scrolling 
region 5-8 

search- back-first-charset-line 
function 3-34 

search-back-f irst-not 

-charset-line function 3-34 

search-char set-backward 
function 3-34 

search-charset- forward 
function 3-34 

search-failure-annunciator 
function 3-57 

search- for-first-char set-line 
function 3-34 

search-for-f irst-not 

-charset-line function 3-34 

search-not-char set-backward 
function 3-34 

search-not-char set- forward 
function 3-34 

searching 3-57 

forward-search-in-line 3-15 
f oward-search 3-3 
get-search-string 3-57 
regexp-search 3-3 
regexp-search-in-line 3-15 
reverse-regexp-search B-8, 
B-25 

reverse-search 3-3 
reverse-search-in-line 3-15 
search-failure-annunciator 
3-57 

select-buffer- find-window 
function 3-54 

select-buffer-window function 
3-53 

select-window function 3-56 
selected-window variable 3-55 
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set-buffer-self-destruct 
function. 3-28 

set-key (ESC X) 3-1 

set-key function 3-21, 3-38 

set-mark function 3-5 

set-permanent-key (ESC X) 3-1 

setq special form 2-8 

skip-back-to-whitespace 
function 3-13 

skip-back-whitespace function 
3-13 

skip-back-whitespace- in-line 
function 3-13 

skip-over-whitespace function 
3-13 

skip-over-whitespace-in-line 
function 3-13 

skip-to-whitespace function 
3-13 

special form 
defcom 3-61 
see form 

special varibale 
see variable 
global 

stop-doing form 2-9 

string form 3-40 

stringlength function 5-5 

stringp predicate 2-6 

subtraction 

-function 2-1 

symbol 2-6, 2-16 
definition of 2-12 



symbol (cont) 
interned 3-26 
property 3-26 
registry 3-26 

symbolp predicate 2-6 



T 



t global variable 2-8 

tab-equivalent variable 3-22 

temp-mark variable 3-5 

temporary 
mark 3-5 
variable 2-10 

terminal support 5-1 

terminal type file 5-1 

the-mark global variable 3-5 

trace 4-5 

tracing function 4-4 
tty-type variable 5-4 



U 



unwind-protect special form 
3-9 



V 



variable 2-3 

binding 2-3 

current-buffer 3-29 

defvar 3-19 

given-tty-type 5-4 

global 2-4, 3-18, 3-35 
*nopoint 2-19 
aim-mode-hook 3-23 
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variable (cont) 
global 

base 2-19 

buffer-creation-hook 3-24 
buffer-destruction-hook 
3-24 

buffer-entrance-hooks 
3-24 

buffer-exit-hook 3-24 
character object 3-41 
close-line-hook 3-24 
current-buffer 3-27 
env-dir 3-20 
ESC 3-16 

f ill-mode-deiimeters 3-39 
f ortran-mode-hook 3-23 
ibase- 2-19 

Idebug-mode-hook 3-23 
lisp-mode-hook 3-23 
mail-mode-hook 3-23 
nil 2-8 
NL. 3-16 
numarg 3-4 
' pll-mode-hook 3-23 
process-dir 3-20 
rmail-mode-hook 3-23 
see mode hook 
t 2-8 

t he-mark 3-5 
X, Y 5-4 
last-minibuf f er-response 
3-16 

Idebug-level 4-2 
local 3-20 

automatically registered 
3-22 

buffer-minor-modes 3-39 
current-buffer-mode 3-38 
nuwindows 3-55 
option 

Idebug-base 4-2 
Idebug-ibase 4-2 
Idebug-prinlength 4-2 
Idebug-prinlevel 4-2 
ospeed 5-3 
parameter 2-4 
previous-buffer 3-29 
region-scroll-availablep 
5-8 

registering 3^20 
selected-window 3-55 



variable (cont) 
special 

se global 
temp-mark 3-5 
temporary 2-4, 2-9 
trace-break-fun 4-7 
trace-printer 4-7 
tty-type 5-4 

view-region-as- lines function 
3-25 



W 



whitespace 

functions 3-13 
management 3-13 

whitespace-to-hpos function 
3-14 

window 3—33 
number 3-55 

pop- up window mode 3-53 
selected 3-55 

window-adjust-lower function 
3-56 

window-adjust-upper function 
3-56 

window-info function 3-56 

windows 

multiple 3-52 

wipe-point-mark function 3-3, 
3-5 

with-mark special form 3-6 

without-modifying special form 
3-8 

without-saving special form 
3-8 

wr ite-out-f ile function 3-3 
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X 

X global variable 5-4 

Y 

Y global variable 5-4 
yesp predicate 3-12 
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